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) 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
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.
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.
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
- sip_audiofile
- Audiofile das nach dem Command fetch abgespielt wird. Das Audiofile muss mit folgendem Command erzeugt werden
- sox <file>.wav -t raw -r 8000 -c 1 -e a-law <file>.alaw
- da nur das raw audio format unterstützt wird. Bitte darauf achten, dass das audiofile und der Pfad dort hin passende Permissions hat, damit FHEM das File auch lesen darf.
- 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_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_ringtime
- Klingelzeit für ausgehende Anrufe.
- sip_user
- User Name des SIP-Clients. Default ist 620.
- sip_waits
- Interne Wartezeit in Sekunden bevor nach nicht erfolgreichem listen ein erneuter Versuch gestartet wird.
- sip_waittime
- Maximale Wartezeit bei listen_for_wfp bis das Gespräch automatisch angenommen wird.
Siehe auch commandref
Set
Das Modul kennt derzeit folgende Commands
- 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.
- Soll statt eines Audiofiles eine DTMF-Sequenz übertragen werden, so muss diese mit einem Prefix '-' versehen werden, also z.B. -#47.
- 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.
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
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_password das in der Fritzbox hinterlegte Passwort eingetragen?
- 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)?
Links
- Forenthread alter Forum-Thread zu FB_SIP.pm und SIP.pm
- Forenthread Forum-Thread zu diesem Modul SIP