SIP-Client

SIP
Zweck / Funktion
SIP-Client für FHEM
Allgemein
Typ	Hilfsmodul
Details
Dokumentation	EN / DE
Support (Forum)	Sonstiges
Modulname	96_SIP.pm
Ersteller	Wzut (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Das Modul SIP ermöglicht die Entgegennahme (DTMF-Töne interpretieren, kontrollierte Annahme) sowie die Durchführung (Audiofile abspielen, DTMF-Töne senden, Textansage) von Anrufen.

Voraussetzungen

FHEM-Server

Für den Remote-Zugang muss das Modul Net::SIP installiert sein; auf einem Raspberry Pi oder unter Ubuntu z. B. mit dem Befehl

sudo cpan install Net::SIP

oder auch

sudo apt-get install libnet-sip-perl

Falls Ihr Text2Speech verwenden wollt

Vorbereitung

• SoX installieren

sudo apt-get install sox

• mp3 Unterstützung für SoX installieren

sudo apt-get install libsox-fmt-mp3

• Text2Speech als Server Device anlegen

define <name z.B myT2S> text2speech none

• beim SIP Device dieses Server Device im Attribut T2S_Device eintragen

SIP-Server

Der SIP-Client muss sich an einem SIP-Server anmelden (Fritzbox, Asterisk, VoIP-Provider). Auf dem SIP-Server, mit dem sich der Client verbinden soll, muss ein User-Account vorhanden sein bzw. angelegt werden. In der Fritzbox muss z.B. ein neues Telefoniegerät vom Typ LAN/WLAN angelegt und ein Passwort (mind. 8 Stellen und Stufe 'gut') vergeben werden. Das erzeugt ein neues internes Device im internen Rufnummernbereich **62x, typischerweise die 620. Es sollte kontrolliert werden, ob bei den Anmeldeinformationen der Benutzername der Nebenstelle entspricht (z.B. 620) und ein Passwort eingetragen ist.

Hardware

Die verwendete Library Net::SIP fordert mehr Ressourcen als RaspberryPi, BananaPi & Co hergeben. Bitte testet, ob Eure Hardware Audofiles sauber abspielen sowie sicher DTMF-Töne empfangen kann und für Euren Einsatzzweck geeignet ist. Erste Tests mit einem Raspi3 lagen im akzeptablen Bereich.

Installation

Erste Schritte

Spätestens nach einem 'update all' sollte das Modul 96_SIP.pm verfügbar sein.

Nun ist der SIP-Client als Device in FHEM anzulegen:

define <name> SIP

Anschließend sollten alle sip_Attribute geprüft und für die eigene Umgebung gesetzt werden. Ebenso ist das Passwort mittels set-Command zu speichern.

Siehe auch commandref

Mögliche Fehlermeldungen

Sollte schon bei define mySIP SIP die Fehlermeldung kommen, dass dieses Modul nicht existiert, dann bitte 'update all' durchführen.

Anwendung

Attribute

Basics & Allgemeines

• sip_from

Meine SIP-Client-Info. Default ist sip:620@fritz.box für ältere Firtz!OS-Versionen. Ab 6.8 ist das Format sip:Benutzername@fritz.box.

• sip_ip

Die IP-Addresse meines FHEM-Servers.

• sip_port

Port der für den SIP-Client genutzt wird. Default ist 5060 und wird automatisch um 10 erhöht wenn der Port nicht frei ist.

• sip_registrar

Hostname oder IP-Addresse des SIP-Servers mit dem sich der Client verbindet. Default ist fritz.box.

• sip_user

User Name des SIP-Clients. Default ist 620. Anmerkung: Passwort wird über "set <device> password mypassword" gesetzt.

• sip_listen

Das Attribut bietet folgende Optionen

- none: keine Aktion ('listen' kann auch nicht manuell gestartet werden)

- dtmf: Beim FHEM-Start geht das Device automatisch in den Status listen und wartet auf DTMF-Anrufer (listen_dtmf). Alternativ kann der Prozess manuell via 'listen' gestartet werden.

- wfp: Beim FHEM-Start geht das Device automatisch in den Status listen wait-fetch-play (listen_wfp). Alternativ kann der Prozess manuell via 'listen' gestartet werden.

- echo: Spielt dem Anrufer nur sein eigenes Echo wider. Sonst nix (siehe auch Anwendungsfälle).

• sip_waittime

Maximale Wartezeit bei listen_wfp bis das Gespräch automatisch angenommen wird.

• sip_ringtime

listen: legt fest wie lange das Modul warten soll bis es den Anruf annimmt. Defaultwert ist 2, das entspricht ca. 1x klingeln.

• sip_force

Pause in Sekunden für nicht erfolgreiche "force"-Anrufe, bis der nächste Versuch gestartet wird.

• sip_filter

ist eine Komma getrennte Liste von Rufnummern oder Rufnummernteilen die festlegen, ob der Client bei listen überhaupt abheben soll.

Bsp.: attr mySIP sip_filter **61,123

**61 = alle DECT Telefone der Fritzbox (610 -619 )

123 = alle Rufnummern in denen die Folge 123 enthalten ist.

Wenn das Attribut sip_filter gelöscht ist werden alle Anrufe angenommen. Das Atrribut entspricht einer Whitelist der Rufnummern die berücksichtigt werden. Anrufe von nicht gelisteten Rufnummern werden einfach ignoriert.

• Anmerkung zum Audioformat

Audiofiles müssen im alaw- oder ulaw-Format vorliegen und können mit folgendem Command erzeugt werden

sox <file>.wav -t raw -r 8000 -c 1 -e a-law <file>.alaw

da nur diese raw audio format unterstützt wird. Unterstützte/erkannte Endungen sind .alaw und .ulaw. Bitte darauf achten, dass das audiofile und der komplette Pfad die passenden Permissions hat, damit der FHEM User das File auch lesen darf.

DTMF empfangen

• sip_dtmf_loop

legt für den listen_dtmf-Modus fest wie oft ein DTMF Code eingeben werden soll ( once oder loop, default ist once ).

Bei 'once' erwartet der SIP-Cleint die Eingabe eines Codes in der angegebenen Länge und beendet den Anruf.

Bei 'loop' startet eine Endlosschleife aus Ansage->Code-Erfassung->Quittung->Loop bis der Anrufer irgendwann auflegt.

• sip_dtmf_size

Die Anzahl der erwarteten DTMF-Töne im listen_dtmf-Modus (1 bis 4)

• sip_audiofile_dtmf

Audiofile das dem Anrufer im listen_dtmf-Modus vorgespielt wird und ihn auffordert einen Code einzugeben. Ist kein File angegeben hört man ein Geräusch.

• sip_audiofile_ok

Audiofile das dem Anrufer im listen_dtmf-Modus als Quittungston vorgespielt wird.

• sip_blocking

Hier kann so etwas wie eine Blacklist von Rufnummern angegeben werden, die explizit weggedrückt werden. Jede Rufnummer die so behandelt werden soll muss zuerst erfolgreich durch den sip_filter durch und kann danach erst aktiv geblockt werden. Die Syntax ist die gleiche wie bei sip_filter, allerdings gibt es hier den Joker .* . Ist dieser gesetzt wird jede ankommende Rufnummer geblockt. Damit lassen sich begrenzt Aktionen auslösen (das Event 'ringing_*' wird nach wie vor ausgelöst und die Rufnummer wird als Reading gesetzt) ohne dass Verbindungskosten anfallen.

Auf anruf warten und annehmen

• sip_audiofile_wfp

Audiofile das nach dem Command fetch abgespielt wird.

• sip_elbc

erlaubte Werte: no | yes. elbc steht für 'End Listen Befor Call'. Bei Option 'yes' wird ein laufender Listen Prozess beendet falls parallel ein Call rausgehen soll. Danach wird der listen wieder neu gestartet.

Anrufen und DTMF senden

• sip_dtmf_send

Bestimmt die Übertragungsart der angegebenen DTMF-Töne und bietet folgende Möglichkeiten:

'audio': Es werden Audiotöne übermittelt

'rfc2833': Es erfolgt eine Übertragung nach RFC2833 (für das menschliche Ohr weniger ansprechend)

Anrufen und etwas senden

• sip_audiofile_call

Audiofile das dem angerufenen bei call vorgespielt wird.

• sip_call_audio_delay

Damit wird festgelegt wie lange bei einem Call mit dem abspielen des Audiofiles gewartet werden soll nachdem man den Anruf angenommen hat. Gültige Werte sind 0 - 3 in 0.25 (1/4) Sekunden Schritten.

Anrufen und etwas sagen

• T2S_Device

Name Eures in FHEM eingerichteten Text2Speech-Devices

• T2S_Timeout

Timeout für die Text2Speech-Konvertierung (könnte ja sein, dass der TTS-Service im Internet überlastet ist)

• audio_converter

Der für die Konvertierung zu verwendende (und vorab installierte) Audiokonverter. Auswahl: sox oder ffmpeg

Siehe auch commandref

Set

Das Modul kennt derzeit folgende Commands

• set <name> password

Passwort für den User sip_user hinterlegen.

• set <name> reset

Stoppt laufende listen-Prozess und initalisiert das Device.

• set <name> call <nummer> [<maxtime>] [<nachricht>] [&]

Startet einen Anruf an die angegebene Nummer.

Optional kann die maxtime angegeben werden. Wird keine angegeben wird der Defaultwert von 30 verwendet.

Optional kann eine Nachricht

- in Form eines Audiofiles angegeben werden. Das File ist mit dem vollen Pfad oder dem relativen ab dem Verzeichnis mit fhem.pl anzugeben. Bitte darauf achten, dass das audiofile und der Pfad dort hin passende Permissions hat, damit FHEM das File auch lesen darf. Die maxtime ist in dem Fall nicht optional sondern zwingend.

- als DTMF-Sequenz angegeben werden. Diese mit einem Prefix '-' versehen werden, also z.B. -#47.

- als Text angegeben werden. Dieser mit einem Prefix '!' versehen werden, also z.B. !Hier spricht dein FHEM.

Bitte hierfür unter 'Voraussetzungen' den Hinweis auf TTS beachten.

Wird der Call mit & (force) beendet signalisiert dies, dass er wichtig ist und unbedingt zugestellt werden muss. Der SIP-Client versucht es dann so lange, bis der Anrufer erreicht wird. WICHTIG: wählt die maxtime groß genug damit das Audiofile auch wirklich komplett abgespielt werden kann, bzw. hört's euch auch bis zum Ende an! Wenn ein priorisierter Anruf vorzeitig endet (quasi NOK) wird er nach 1 Minute wiederholt, und zwar so lange bis er erfolgreich war. Wollt Ihr den Ablauf stoppen bitte das von der Wiederholungsschleife gesetzte at löschen, es befindet sich im gleichen Raum wie euer SIP Device. Z.Z ist diese 1 Minute noch fix, wenn es bei euch sauber läuft werde ich dafür ein neues Attribut spendieren.

Werden mehrere Set Call unmittelbar hintereinander abgesetzt, werden diese intern gestackt und nacheinander abgearbeitet.

• set <name> listen

Manueller Start des listen-Prozesses. Setzt voraus, dass die Variable sip_listen auf dtmf oder wfp gesetzt ist:

dtmf: Der SIP-Client wird in einen Status versetzt in dem er automatisch Anrufe annimmt. Bei einem Anruf wird im Reading 'caller' die Nummer bzw. Id des Anrufers angezeigt. Dem Anrufer wird der eigene Ton als Echo zurückgespielt. Über die Eingabe von # gefolgt von 2 Zahlen und anschließendem Auflegen kann eine Zahl an das Reading dtmf übergeben werden. Voraussetzung: Das anrufende Telefon ist auf Tonwahl gestellt (DTMF).

wfp: Der SIP-Client wird in einen Status versetzt in dem er auf Anrufe wartet (wfp steht für wait-fetch-play). Erfolgt ein Anruf an den Client, wechselt das Reading 'caller_state' zu 'ringing_*', im Reading 'caller' wird die Nummer bzw. Id des Anrufers angezeigt. Nun kann das Gespräch via set-Command 'fetch' angenommen oder der Anruf via 'reject' explizit abgelehnt werden. Das als sip_audiofile angegebene File wird abgespielt. Anschließend wechselt der Status wieder zu listen_wfp.

• set <name> fetch

Anruf im listen_wfp-Modus annehmen.

• set <name> reject

Anruf im listen_wfp-Modus ablehnen.

Readings

• call: Die Rufnummer des ausgehenden Anrufs.
• call_state: Status für ausgehende Anrufe.
• caller: Die Rufnummer bzw. Info des aktuellen Anrufers.
• caller_state: Status für eingehende Anrufe.
• dtmf: Die via Tonwahl (DTMF) eingegebenen Zahlen.
• state: Der Status des Devices.

Anwendungsbeispiele

Anruf tätigen und Sound abspielen

• Den Anruf initiieren

 set <device> call <nummer> [<dauer>] [<audiofile oder Textnachricht>]
 set mySip call 081547111 30 ./tada.alaw
 set mySip call 081547111 30 !Hier ist dein FHEM Server

• Die Default-Dauer beträgt 30 Sekunden.
• Wird kein Audiofile angegeben, wird nur die Verbindung hergestellt und nach der Anrufdauer wieder unterbrochen.
• Anmerkung: Das Audiofile muss das Format PCM/8000 haben.
• Der Angerufene nimmt das Gespräch entgegen, das Audiofile wird abgespielt.

Anruf tätigen und DTMF-Töne senden

• Den Anruf initiieren

set <device> call <nummer> <dauer> <-tastenkombination>

• Die Tastenkombination muss mit einem Minus (-) nach der Zielnummer folgen, also z.B. **1 -#23
• Der Angerufene nimmt das Gespräch entgegen, die Tonfolge wird abgespielt.

Auf Anruf warten und DTMF-Töne empfangen

• Der SIP-Client wird in den Listen-Modus versetzt.

Das Attribut sip_listen auf dtmf setzen und

set <device> listen

• Die Nebenstelle des SIP-Clients wird von einem DTMF-fähigen Telefon aus angerufen.
• Wenn der SIP-Client das Gespräch angenommen hat, betätigt man #, gefolgt von zwei Ziffern und legt dann wieder auf. Wichtig: Es müssen immer genau 3 Tasten betätigt werden (# und nm), damit das Reading dtmf gefüllt wird. n und m müssen zwei verschiedene Zahlen sein (0-9) oder ein Stern.
• Im Reading dtmf ist diese zweistellige Zahl zu sehen und kann ggf. mit einem notify ausgewertet werden.

Auf Anruf warten und kontrolliert annehmen

• Der SIP-Client wird in den Listen-Modus versetzt.

Das Attribut sip_listen auf wfp setzen und

set <device> listen

• Die Nebenstelle des SIP-Clients wird angerufen.
• Im Reading caller ist die Nummer bzw. die Info des Callers zu sehen, im caller_state erscheint 'ringing'.
• Soll der Anruf angenommen werden setze ich den Status des Devices mittels set auf fetch:

set <device> fetch

• Der SIP-Client nimmt den Anruf an und spielt das im Attribut sip_audiofile angegebene File ab.
• Der SIP-Client legt auf und geht wieder in den Status listen_wfp.

Auf Anruf warten und Aktion auslösen

• Der SIP-Client wird in den Listen-Modus versetzt.

Das Attribut sip_listen auf wfp setzen und

set <device> listen

• Die Nebenstelle des SIP-Clients wird angerufen.
• Im Reading caller ist die Nummer bzw. die Info des Callers zu sehen, im caller_state erscheint 'ringing'.
• FHEM kann auf Grund dieser Events eine Aktion durchführen.
• Der Anruf wird dann von FHEM abgebrochen. Dafür wird der Befehl reject genutzt:

set <device> reject

• Der Anrufer weiß auf Grund der Ablehnung, dass FHEM aktiv war.
• Der SIP-Client legt auf und geht wieder in den Status listen_wfp.

Fritzbox + Doorline - Telefonklingeln beenden

Szenario: Als Türklingel ist eine Doorline im Einsatz die auf Direktannahme eingestellt ist. Klingelt jemand an der Tür, erfolgt ein 'Anruf' an die in der Rufgruppe definierten Telefone. Man kann den Anruf entgegennehmen, um zu hören wer an der Tür ist, bevor man die Tür öffnet. Geht man direkt zur Tür, klingeln die Telefone insgesamt 30 Sekunden lang bis sie verstummen. Hat man die Haustür mit einem Türkontakt versehen, hilft folgender Ansatz:

• Der SIP-Client wird in der Fritzbox in die Rufgruppe der Türklingel aufgenommen.
• Das Attribut 'sip_listen' wird auf 'wfp' gesetzt.
• Der SIP-Client wird in den Listen-Modus 'wait-fetch-play' versetzt (Die sip_waittime sollte größer als die Klingeldauer der Doorline sein).

set <device> listen

• Klingelt jemand an der Tür, wird unter anderem die Nebenstelle des SIP-Clients angerufen.
• Über ein DOIF greift man die Kombination SIP-Client caller_state 'ringing' und Haustürkontakt closed->open ab und
• setzt den Status des Devices mittels set auf fetch:

set <device> fetch

• Der SIP-Client nimmt den Anruf an und spielt das im Attribut sip_audiofile angegebene File ab.
• Die Telefone verstummen.

In FHEM sieht das dann z.B. so aus:

Es gibt ein Device HaustuerStatus das den Status des Türkontaktes abbildet: "closed" oder "open".

Es wird ein Dummy-Device HaustuerStatusVar für die Status des Automaten angelegt:

define HaustuerStatusVar dummy

Und ein DOIF TuerklingelAus:

define TuerklingelAus DOIF 
(([HaustuerStatus:state] eq "closed") and ([FhemSipClient:caller_state] eq "ringing.*") and ([FhemSipClient:caller] eq "Klingel sip:**12\@fritz.box")) 
(set HaustuerStatusVar ringing;; set HM_4A4047_Mp3 playTone 001 1 10) 
DOELSEIF 
(([HaustuerStatus:state] eq "open") and ([HaustuerStatusVar:state] eq "ringing")) 
(set FhemSipClient fetch;; set HaustuerStatusVar on) 
DOELSEIF 
(([HaustuerStatus:state] eq "closed") and ([HaustuerStatusVar:state] ne "off")) 
(set HaustuerStatusVar off)

Der Caller "Klingel sip:**12\@fritz.box" setzt sich aus dem in der Fritzbox vergebenen Namen, der Nebenstelle (**12 ist eine Doorline mit einem Taster, bei zweien gilt es **11 und **12 zu beachten) sowie dem syntaktischen Drumherum sip:nebenstelle\@fritz.box zusammen. Achtet bitte auf den "\" vor dem "@", damit regex nicht mosert.

HM_4A4047_Mp3 ist übrigens mein mobiler MP3-Tür-/Funkgong der zur Unterstützung einen Gong abspielt.

Nervende Werbeanrufe

Ihr kennt das sicher: Unbekannte Rufnummer, man nimmt das Gespräch an und hat entweder irgendwas gewonnen, einen Werber oder ein "Umfrage" dran. Unterm Strich - man will Dir was verkaufen.

Phase 1: Fritzbox, Rufbehandlung, neue Rufnummernsperre, Nummer eintragen.

Phase 2: Derselbe Werber taucht unter einem ganzen Kontingent von Rufnummern auf. Blocken alleine reicht dir nicht mehr, du willst Rache.

Phase 3: Du definierst in FHEM den SIP-Client und startest ihn im listen-Modus "echo". In der Fritzbox leitest du alle eingehenden Anrufe auch an den SIP-Client weiter. Dem SIP-Client gibt du über sip_filter die Werber-Rufnummer als Filterarguiment mit.

Phase 4: Jetzt bin ich (der Autor dieses Anwendungsfalles) neugierig. Postet Eure Erfahrung mit diesem Modus gerne im Forums-Thread.

Bekannte Probleme / Fehlersuche

Fehler bei der Registrierung an der Fritzbox

Fritzbox

• Ist das Device für den SIP-Client in der Fritzbox unter Telefonie > Telefoniegräte gelistet?
• Geräteeinstellungen ändern: Ist für das Device unter 'Anmeldedaten' die Durchwahl als Benutzername angegeben?
• Ist der in dieser Ansicht angegebene 'Registrar' mit der im Attribut sip_registrar identisch? Im Zweifelsfalle die IP-Adresse statt 'fritz.box' verwenden.
• FitzOS ab 6.80: Wurde nach Definition des Gerätes an einem anderen bekannten Gerät der Bestätigungscode eingegeben?
• Wurde in der Fritzbox ein Passwort von mind. 8 Stellen und Sicherheitsstufe 'gut' vergeben? Andernfalls kann es zu einem Registrierungsfehler 404 kommen.

FHEM

Wurde das Passwort mittels set <mydevice> password <meinpasswort> gesetzt?

Attribute des Devices prüfen:

• Ist unter sip_from 'sip:620@fritz.box' die von der Fritzbox vergebene Durchwahl angegeben? Ab Fritz!OS 6.8 gilt: Ist das Format sip:Benutzername@fritz.box eingehalten?
• Ist unter sip_user die von der Fritzbox vergebene Durchwahl angegeben?
• Ist unter sip_registrar die IP-Adresse der Fritzbox eingetragen ('fritz.box' wird manchmal nicht korrekt aufgelöst)?
• Ist unter sip_ip die IP-Adresse des FHEM-Servers eingetragen (z.B. 192.168.178.47 angeben, keine Adresse aus dem 127er-Segment)?
• Probleme mit dem Standard-Port 5060? Auf 5070 erhöhen.

Erzeugung eines passenden Audiofiles

Eine Alternative zu sox ist ffmpeg. Damit kann direkt von mp3 ins Zielformat konvertiert werden:

ffmpeg -i meinfile.mp3 -f alaw -ar 8000 meinfile.alaw

Keine korrekte DTMF-Erkennung auf einem Pi

Raspi, Raspi2 und BanaPi sind nicht leistungsstark genug für die Erkennung von DTMF-Tönen. Ab Raspi3 scheint's zu funktionieren.

Wer trotzdem auf einem "kleinen" Pi die DTMF-Erkennung gemäß RFC2833 nutzen möchte, kann in der DTMF.pm die Zeile 75

###$sub{$type} = _dtmf_xtc_audio(%pargs);

für die Audio-Erkennung auskommentieren. Zu finden ist DTMF.pm z.B. unter /usr/lib/perl5/site_perl/5.18.2/Net/SIP. Konsequenz: Moderne, RFC2833-unterstützende Geräte können genutzt werden, ältere Telefone mit Tonwahl nicht.

Links

• Forenthread alter Forum-Thread zu FB_SIP.pm und SIP.pm
• Forenthread Forum-Thread zu diesem Modul SIP