
Doku zu opt_caiviar
===================

"Caiviar is an Interactive Voice Response (IVR) System based on CAPI. 
It runs on Linux and Windows systems, and supports Text-To-Speech (most 
notably Realspeak and Festival), multithreading, Barge In, 3 Party 
Conference, G3 Fax etc."
							(http://www.caiviar.org/)


opt_caiviar stellt den caiviar capiserver von http://www.caiviar.org/ für
fli4l zur Verfügung. Anders als z.B. opt_mtgcapri gibt es dafür jedoch
keine Netzwerk-CAPI sondern vielmehr eine API für Java, Perl und Python.
Caiviar erlaubt es damit eigene Programme zu entwickeln, die über die im
fli4l-Router eingebaute ISDN-Karte kommunizieren.
Um das Paket noch erträglich klein zu halten befindet sich nur ein Teil 
der Sourcen findet unter /src/caiviar/caiviar-0.3.5_part. Die kompletten
Sourcen stehen unter http://www.caiviar.org/caiviar-0.3.5.tar.gz zur Verfügung.

ACHTUNG:
Der Einsatz diese Packets ist nur bei Installation auf einem großen Datenträger 
möglich. Der Caiviar-Server benötigt ca. 700KB, der Client auf dem fli4l auf Grund 
der nötigen chroot-Umgebung ca. 4,8MB zusätzlich!


Caiviar bietet folgende Möglichkeiten:
fax:	es können derzeit sff und ps-Dateien gefaxt werden
		prinzipiell ist auch html möglich, ich habe aber noch kein 
		funktionierendes html2ps gefunden.
play:	Caiviar kann Teilnehmer anrufen und vorhandene Audidateien abspielen
		dazu ist es notwendig, dass die Dateien als 8Bit Mono alaw mit 8000Hz 
		Samplingfrequenz vorliegen.
		Audacity kann solche Dateien erzeugen, ich habe aber noch keinen Weg
		gefunden, dass die damit erzeugten Dateien auch am Telefon gut klingen.
		Besser ist unter Linux sox:
			sox infile.wav -r 8000 -c 1 outfile.la
		erzeugt als outfile.la eine nutzbare und meist vernünftig klingende Datei
dtmf:	Caiviar kann weiterhin beliebige DTMF-Töne erzeugen und an die gewählte
		Nummer übertragen
tts:	Caiviar unterstützt prinzipiell auch TTS (Text-to-Speach), also das 
		Vorlesen von Texten. Die derzeitige Version des Opts unterstützt dies
		jedoch noch nicht.

Zur Steuerung des caiviar capiserver steht das Script caiviar.sh auf dem fli4l zur 
Verfügung. Es akzeptiert die Parameter start, stop, test und status.


Variablen:
==========================
		
OPT_CAIVIAR='yes'				#aktiviert bzw. deaktiviert das Opt

CAIVIAR_PORT='7437'				#Port auf dem der caiviar capiserver lauscht

CAIVIAR_AUTOSTART='yes'			#soll der caiviar capiserver autmatisch gestartet werden?
								
CAIVIAR_MSISDN='41'				#MSISDN die caiviar für Telefonverbindungen standardmäßig nutzt,
								#kann im Clientprogramm anders gewählt werden
								
CAIVIAR_LOCALHOST_ONLY='yes'	#Soll caiviar nur für localhost verfügbar sein oder auf allen
								#Schnittstellen lauschen?
								#ACHTUNG: bei CAIVIAR_LOCALHOST_ONLY='no' lauscht caiviar auf 0.0.0.0

optionale Variablen:
==========================							
CAIVIAR_CONTROLLER='1,2'		#welche ISDN-Controller soll caiviar nutzen?
								#Bsp: 1 Fritzcard eingebaut --> 1,2 oder 1-2
								#Syntax: 1-3 | 1,4,5 | 1-2, 5
								
CAIVIAR_EXPERT_MODE="no"		#erlaubt es eine eigene Konfigurationsdatei unter 
								#$config_dir$/etc/caiviar/ivr.properties zu nutzen.
								#Bsp. siehe config/etc/caiviar/ivr.properties
								
CAIVIAR_LOGFILE='/var/log/caiviar.log'	#soll caiviar in eine Datei loggen?
										#ACHTUNG: veranlasst evtl. vorhandene HDDs aus dem Standbye 
										#aufzuwachen

CAIVIAR_LOGLEVEL='9'					#Loglevel für Datei

CAIVIAR_SCREENLOGLEVEL='6'				#Loglevel be manuellem Start in der Console

CAIVIAR_DIR='/var/caiviar'				#in welchem Verzeichnis soll caiviar gestartet werden?
										#Verzeichnis muss beschreibbar sein da sonst weder gefaxt noch
										#Audodateien abgespielt werden können
										
CAIVIAR_CLIENT='yes'					#soll das Clientprogramm mit auf den Router übertragen werden?
										#ACHTUNG: benötigt ca. 3MB Platz
										
CAIVIAR_CLIENT_DIR='/var/run/cc'		#in welchem Verzeichnis soll die für CAIVIAR_CLIENT nötige
										#chroot-Umgebung angelegt werden?



caiviarclient:
==========================

ACHTUNG:
	caiviarclient.sh und caiviarclient.jar sollten direkt nach Ende der gewünschten
	Aktion das Gespräche beenden. In allen bisherigen Tests hat das zuverlässig funkioniert.
	Es wird jedoch keinerlei Gewähr übernommen, dass dies auch wirklich immer garantiert 
	werden kann. Falls es also zu einem Fehler kommt und der Angerufene den Anruf nicht 
	beendet kann es als unter Umständen zu ausufernden Telefonrechnungen kommen.

Der beiliegende Client erlaubt die Nutzung der grundsätzlichen Möglichkeiten
von opt_caiviar. Der Client liegt in zwei Versionen bei:

caiviarclient.jar: 	Ein einfacher Client, geschrieben in Java, der die grundsätzlichen
					Möglichkeiten von opt_caiviar zeigt. Die Sourcen stehen unter 
					src/caiviar zur Verfügung. Benötigt eine Java Runtime

caiviarclient:		Der Client der auf dem fli4l zum Einsatz kommt. Dafür wurde
					caiviarclient.jar mit Hilfe des JavaNativeCompilers 1.1.1 von
					http://jnc.mtsystems.ch/ nativ compiliert. Für den Einsatz auf
					dem Router ist jedoch wegen nötiger libc immer noch eine 
					chroot-Umgebung notwendig.


Anwendungsbeispiele:
==========================
Die Funktionalität von caiviarclient.sh (Wrapper um nativen caiviarlcient) und
caiviarclient.jar ist identisch. Am Client bietet sich jedoch meist das 
deutlich kleinere caiviarclient.jar an.

	"java -jar caiviarclient.jar -h"	gibt eine kurze Hilfe zur Verwendung aus


per ssh auf dem fli4l: wähle die Nummer 016044556677 und spiele nach
Annahme des Anrufs die Datei /data/audio/hello.la 
	caiviarclient.sh -a play -n 016044556677 -f /data/audio/hello.la

Wähle Nummer 31 und sende die DTMF-Sequenz "#61" (so öffne ich meine Haustür ;-))
	java -jar caiviarclient.jar -a dtmf -n 31 #61

Wähle die Nummer 016044556677, wobei eine vorangestellte 0 zur Amtsholung notwendig
ist. Sobald der Teilnehmer abhebt wir ihm die Datei audiofile.la vorgespielt.
audiofile.la muss bereits im richtigen Format vorliegen (sox infile.wav -r 8000 -c 1 outfile.la)
	java -jar caiviarclient.jar -a play -n 0016044556677 -f audiofile.la
	
Faxe die Datei faxfile.sff an die Nummer 016044556677. Der caiviar capiserver lauscht
aber nicht auf localhost:7437 sondern auf router.home:1234.
	java -jar caiviarclient.jar -a fax -n 016044556677 -f faxfile.sff -s router.home -p 1234

Idee: Falls ich von meinem Handy mit der Nummer 016044556677 die MSISDN anrufe,
die die Telefonalage auf die interne Nummer 48 umsetzt, dann wähle "31" und sende
die DTMF-Sequenz "#61". (--> das öffnet bei mir die Haustür)
in isdn.txt folgendes Eintragen:
	TELMOND_CMD_1='48 0016044556677 caiviarclient.sh -a dtmf -n 31 #61'
	
#------------------------------------------------------------------------------
## Creation:     22.08.2007  Christoph Fritsch <fli4l@dechristo.net>
## Last Update:  22.08.2007  Christoph Fritsch <fli4l@dechristo.net>
#------------------------------------------------------------------------------
