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 cpanm 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 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 und sicher DTMF-Töne empfangen kann und für Euren Einsatzzweck geeignet ist.

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.

Mögliche Fehlermeldungen

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

Anwendung

Define

define <name> SIP

Anschließend sollten alle sip_Attribute geprüft und für die eigene Umgebung gesetzt werden.

Siehe auch commandref

Attribute

Basics & Allgemeines

• sip_from

Meine SIP-Client-Info. Default ist sip:620@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_for_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_for_wfp). Alternativ kann der Prozess manuell via 'listen' gestartet werden.

• sip_waittime

Maximale Wartezeit bei listen_for_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.

call: sip_ringtime wird nicht mehr verwendet. Wird keine Maximale Zeit angegeben so wird der Default Wert von 30 Sekunden verwendet.

• 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 Pfad dort hin passende Permissions hat, damit FHEM das File auch lesen darf.

DTMF empfangen

• sip_dtmf_loop

legt für den listen_for_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 Ansagee->Code-Erfassung->Quittung->Loop bis der Anrufer irgendwann auflegt.

• sip_dtmf_size

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

• sip_audiofile_dtmf

Audiofile das dem Anrufer im listen_for_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_for_dtmf-Modus als Quittungston vorgespielt wird.

Auf anruf warten und annehmen

• sip_audiofile_wfp

Audiofile das nach dem Command fetch abgespielt wird.

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.

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)

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> [<ringtime>] [<nachricht>]

Startet einen Anruf an die angegebene Nummer.

Optional kann die ringtime angegeben werden. Wird keine angegeben zieht das Attribut sip_ringtime. Default ist 10.

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 ringtime ist in dem Fall nicht optional sondern anzugeben.

* 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.

• 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 werden. Das als sip_audiofile angegebene File wird abgespielt. Anschließend wechselt der Status wieder zu listen_for_wfp.

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>]

• Die Default-Dauer beträgt 10 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_for_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.

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?

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?
• Ist unter sip_user die von der Fritzbox vergebene Durchwahl angegeben?
• Ist unter sip_registrar die IP-Adresser der Fritzbox eingetragen?
• Ist unter sip_ip die IP-Adresse des FHEM-Servers eingetragen (z.B. 192.168.178.47 angeben, keine Adresse aus dem 127er-Segment)?

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

Links

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