
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/ fr
fli4l zur Verfgung. Anders als z.B. opt_mtgcapri gibt es dafr jedoch
keine Netzwerk-CAPI sondern vielmehr eine API fr 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 ertrglich 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 Verfgung.

ACHTUNG:
Der Einsatz diese Packets ist nur bei Installation auf einem groen Datentrger 
mglich. Der Caiviar-Server bentigt ca. 700KB, der Client auf dem fli4l auf Grund 
der ntigen chroot-Umgebung ca. 4,8MB zustzlich!


Caiviar bietet folgende Mglichkeiten:
fax:	es knnen derzeit sff und ps-Dateien gefaxt werden
		prinzipiell ist auch html mglich, 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 vernnftig klingende Datei
dtmf:	Caiviar kann weiterhin beliebige DTMF-Tne erzeugen und an die gewhlte
		Nummer bertragen
tts:	Caiviar untersttzt prinzipiell auch TTS (Text-to-Speach), also das 
		Vorlesen von Texten. Die derzeitige Version des Opts untersttzt dies
		jedoch noch nicht.

Zur Steuerung des caiviar capiserver steht das Script caiviar.sh auf dem fli4l zur 
Verfgung. 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 fr Telefonverbindungen standardmig nutzt,
								#kann im Clientprogramm anders gewhlt werden
								
CAIVIAR_LOCALHOST_ONLY='yes'	#Soll caiviar nur fr localhost verfgbar 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 fr 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 knnen
										
CAIVIAR_CLIENT='yes'					#soll das Clientprogramm mit auf den Router bertragen werden?
										#ACHTUNG: bentigt ca. 3MB Platz
										
CAIVIAR_CLIENT_DIR='/var/run/cc'		#in welchem Verzeichnis soll die fr CAIVIAR_CLIENT ntige
										#chroot-Umgebung angelegt werden?



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

ACHTUNG:
	caiviarclient.sh und caiviarclient.jar sollten direkt nach Ende der gewnschten
	Aktion das Gesprche beenden. In allen bisherigen Tests hat das zuverlssig funkioniert.
	Es wird jedoch keinerlei Gewhr 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 Umstnden zu ausufernden Telefonrechnungen kommen.

Der beiliegende Client erlaubt die Nutzung der grundstzlichen Mglichkeiten
von opt_caiviar. Der Client liegt in zwei Versionen bei:

caiviarclient.jar: 	Ein einfacher Client, geschrieben in Java, der die grundstzlichen
					Mglichkeiten von opt_caiviar zeigt. Die Sourcen stehen unter 
					src/caiviar zur Verfgung. Bentigt eine Java Runtime

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


Anwendungsbeispiele:
==========================
Die Funktionalitt 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: whle 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

Whle Nummer 31 und sende die DTMF-Sequenz "#61" (so ffne ich meine Haustr ;-))
	java -jar caiviarclient.jar -a dtmf -n 31 #61

Whle 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 whle "31" und sende
die DTMF-Sequenz "#61". (--> das ffnet bei mir die Haustr)
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>
#------------------------------------------------------------------------------
