add experimental mISDN channel driver (issue #4077)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@6910 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 363 insertions, 0 deletions

diff --git a/doc/README.misdn b/doc/README.misdn
new file mode 100755
index 000000000..ee4e24c5f
--- /dev/null
+++ b/doc/README.misdn
@@ -0,0 +1,363 @@
+mISDN Channel Driver for Asterisk PBX
+======================================
+
+
+This package contains the mISDN Channel Driver for the Asterisk PBX. It 
+supports every mISDN Hardware and provides an interface for asterisk. 
+
+Features: 
+
+* NT and TE mode
+* PP and PMP mode
+* BRI and PRI (with BNE1 and BN2E1 Cards)
+* DTMF Detection in HW+mISDNdsp (much better than asterisks internal!)
+* Display Messages to Phones (which support display msg)
+* HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
+* Screen/ Not Screen User Number
+* Basic EchoCancellation 
+* Volume Control 
+* Crypting with mISDNdsp (Blowfish)
+* Data (HDLC) callthrough 
+* Data Callin (with app_ptyfork +pppd)
+* echo cancellation
+* some other
+
+Supported Hardware:
+
+chan_misdn supports any mISDN compatible Hardware. Especially the 1-8 Port
+BRI Cards available from http://shop.beronet.com
+
+Overview
+--------
+
+- Fast Installation Guide
+- Pre-Requisites
+- Compilation 
+- Installation
+- Configuration
+- Dial and Options String
+- misdn cli commands
+- Debugging and sending Bugreports
+- Examples
+- Known working Configurations
+- Known Problems
+- Changes
+
+
+Fast Installation Guide
+-----------------------
+
+You have two options on how to install chan_misdn.
+
+(1) Requirements: 
+      - mISDN and mISDNuser from jolly (see Pre-Requisites below)
+    Installation: 
+	  - cd <asterisk-src-dir>/channels/misdn
+	  - edit Makefile so that MISDNUSER points to your mISDNuser directory
+	  - run 'make'
+	  - cd <asterisk-src-dir>
+	  - compile and install asterisk via 'make install'
+
+(2) Requirements:
+      - Asterisk headers and Kernel headers
+    Description:
+      The Makefile gets the newest mISDN and mISDNuser Sources from 
+	  jollys webpage and the newest release of chan_misdn from beronets 
+	  Servers. After that it compiles and installs everything (hopefully).
+    Installation:
+      - cd /usr/src
+      - wget http://www.beronet.com/downloads/install-misdn.tar.gz
+	  - tar zxf install-misdn.tar.gz
+	  - cd install-misdn
+	  - make install
+
+
+Pre-Requisites
+--------------
+
+To compile and install this driver, you'll need at least one mISDN Driver, the
+mISDNuser package and the asterisk includes (which will be inside of the
+sources). Chan_misdn works with both, the current stable release and the cvs-head version of Asterisk.
+
+To get the mISDN stuff please follow the instructions at
+http://www.isdn4linux.de.  Please Note that mISDN works good for the
+linux-2.6.x kernels. Some of the mISDN drivers do not compile against the
+2.4.x or older kernels, you can patch them, but than you'll get myterius
+errors.
+
+ I use Kernels > 2.6.9 and it works perfect. with kernels >= 2.6.10 there is a
+very litle bug in hfc_multi.c which causes the module not to compile, it can
+be easyly fixed by changenging pci_findsubsys to pci_getsubsys in code.
+
+Ok so far so good, now follow the compilation instructions.
+
+!! Dont forget to create the /dev/mISDN device node.
+
+Compilation 
+-----------
+
+!! Be aware, in the actual mISDNuser package theres a bug in the Makefile
+!! the compilation stops near iapplication.h, this isn't very important
+!! at this step you are ready. 
+
+After you've successfully installed mISDN, mISDNuser and asterisk, you should
+modify the Makefile in the chan_misdn source path. There you can tell the
+Makefile where to install the driver, sample-conf, and most important where it
+can find the linux kernel includes, the mISDNuser package and the asterisk
+includes.  If you use the Head-Revision of Asterisk (or at least a newer
+version than stable) uncomment the CCFLAGS+=-DASTERISK_STABLE, the stable
+version of asterisk is at the moment v1-0-X as cvs tag.
+
+Now you can type in: 
+
+make
+
+This should compile chan_misdn.so, if theres an error check the paths in the
+Makefile again.
+
+
+Installation
+------------
+
+After successful compilation of chan_misdn, you should simply type in:
+
+make install 
+
+as privileged user to put chan_misdn.so in the asterisk modules
+directory.
+
+You should see a Msg like: "Successfully installed chan_misdn". 
+Congratulations. 
+
+Theres a sample init.d script for loading the mISDN modules (mISDN.sample),
+simply copy it to /etc/init.d/ and modify it, there you can enter your cards.
+
+!! Forget to use capi together with chan_misdn. 
+
+
+
+Configuration
+-------------
+
+First of all you must configure the mISDN drivers. Each driver module has got
+an options and layermask option, which tells the driver wether to start in
+TE,NT, PP or PMP mode (there are lots more please read docs in misdn for
+that).
+
+After thinking about the above you'll probably want to configure the
+misdn.conf file which resides in the asterisk-config directory.
+
+The misdn.conf file contains a "general" Section, and user sections which
+contain misdn port settings and different asterisk contexts.
+
+The general section contains especially a variable named context with which
+the default context is set. There is also the very important debug variable
+which you can set from the asterisk cli (command line interface) or in this
+configfile, bigger numbers will lead to more debug output. Theres also a
+tracefile options, which takes a path+filename where debug output is written
+to.
+
+The user Sections have names which are unequal to "general". Those sections
+contain the ports variable which mean the mISDN Ports. Here you can add
+comma-sepperated multiple ports. 
+
+Espacially for TE-Mode Ports there is a msns variable. This variable tells the
+chan_misdn driver to listen for incomming calls with the given msns, you can
+insert a '*' as single msn, which leads in getting every incomming call (if
+you want to share on PMP TE S0 with a asterisk and a phone or isdn card you
+should insert here the msns which you'll like to give the asterisk).  Finally
+a context variable resides in the user sections, which tells chan_misdn where
+to send incomming calls to (extension.conf).
+
+In NT-Mode Ports there is a new option, directly after the port number you can
+write ptp, this enables PP Mode for this port, please look at misdn.conf for
+an example.
+
+When everything worked you should get the asterisk running.
+
+
+Dial and Options String
+-----------------------
+
+The Dialstring of chan_misdn got more complex, because we added more features,
+so the generic dialstring looks like:
+
+mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
+
+The Optionsstring looks Like:
+:<optchar1><OptParam1>:<optchar2><OptParam2>
+
+the ":" character is the delimeter.
+
+The available Optchars are: 
+	d - Send display text on called phone, text is the optparam
+	n - don't detect dtmf tones on called channel
+	h - make digital outgoing call
+	c - make crypted outgoing call, param is keyindex
+	e - perform echo cancelation on this channel, takes taps as 
+	arguments (32,64,128,256)
+	s - send Non Inband DTMF as inband
+	vr - rxgain control
+	vt - txgain control
+
+
+chan_misdn registers a new application "misdn_set_opt" when loaded. This 
+application takes the Optionsstring as argument. The Syntax is:
+
+misdn_set_opt(<OPTIONSSTRING>)
+
+
+When you set options in the dialstring, the options are set in the external
+channel. When you set options with misdn_set_opt, they are set in the current
+incoming channel. So if you like to use static encryption, the scenario looks
+as follows:
+
+Phone1 --> * Box 1 --> PSTN_TE 
+PSTN_TE --> * Box 2 --> Phone2
+
+The Encryption must be done on the PSTN sides, so the dialplan on the boxes
+are:
+
+* Box 1:
+exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)
+
+* Box 2:
+exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
+exten => ${CRYPT_MSN},2,dial(${PHONE2})
+
+
+
+
+misdn cli commands
+------------------
+
+At the asterisk cli you can try to type in: 
+
+misdn <tab> <tab>
+
+Now you should see the misdn cli commands: 
+
+- clean
+	-> pid 		(cleans a broken call, use with care, leads often
+			 to a segmentation fault)
+- send
+	-> display	(sends a Text Message to a asterisk channel, 
+			 this channel must be an misdn channel)
+- set
+	-> debug	(sets debug level)
+- show
+	-> config	(shows the configuration options)
+	-> channels	(shows the current active misdn channels)
+	-> channel	(shows details about the given misdn channels)
+	-> stacks	(shows the currend ports, there protocols and states)
+	-> fullstacks	(shows the current active and inactive misdn channels)
+
+- restart 
+	-> port		(restarts given port (L2 Restart) )
+
+- reload 		(reloads misdn.conf)
+
+You can only use "misdn send display" when a asterisk channel is created and
+isdn is in the corect state, correct state means that you have established a
+call to another phone (mustnt be isdn though).
+
+Then you use it like this:
+
+misdn send display mISDN/1/101 "Hello World!"
+
+where 1 is the Port of the Card where the phone is plugged in, and 101 is the
+msn (callerid) of the Phone to send the text to.
+
+
+
+Debugging and sending Bug-Reports
+---------------------------------
+
+If you encounter problems, you should set up the debugging flag, usually debug=1 should be enough. the Messages are divided in asterisk and misdn parts. Misdn Debug messages begin with an 'I', asterisk messages begin with an '*', the rest is clear I think. 
+
+Please take a trace of the problem and send this trace via mail to bugs@beronet.com
+
+
+Examples
+--------
+
+here some examples of how to use chan_misdn in the dialplan (extensions.conf): 
+
+
+[globals]
+OUT_PORT=1 ; The physical Port of the Card
+OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
+
+[misdnIn]
+exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN})
+exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
+exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
+exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)
+
+In the last line you will notice the last argument (Hello), this is sended
+as Display Message to the Phone.
+
+
+Known working Configurations
+----------------------------
+
+In this Section I'll put working configurations for chan_misdn. Beware It
+seems that between Kernel 2.6.3 and Kernel 2.6.8 there were lots of mISDN
+Bugs. I use Kernel 2.6.9 now, it works quite ok, Kernel 2.6.10+ has changed
+the pci_find_subgsys funktion, so hfc_multi from mISDN doesn't compile against
+it, you can just change pci_find_subsys to pci_get_subsys, this works.
+
+
+- chan_misdn-0.0.3-rc1: 	
+	* linux-kernel >= 2.6.3 (but at least 2.6) 
+	* asterisk >= v1-0 
+	* mISDN/mISDNuser since September/04
+
+- chan_misdn-0.0.3-rc3: 	
+	* linux-kernel >= 2.6.3 (but at least 2.6) 
+	* asterisk >= v1-0.2 
+	* mISDN/mISDNuser since December/04
+
+- chan_misdn-0.0.3-rc4: 	
+	* linux-kernel >= 2.6.8 (but at least 2.6) 
+	* asterisk >= v1-0.2 
+	* mISDN/mISDNuser head on cvs.isdn4linux.de
+
+- chan_misdn-0.0.3-rc6: 	
+	* linux-kernel >= 2.6.8 (but at least 2.6) 
+	* asterisk >= v1-0.2 
+	* mISDN/mISDNuser head on cvs.isdn4linux.de
+
+- chan_misdn-0.1.0
+	* linux-kernel >= 2.6.8 (but at least 2.6) 
+	* asterisk >= v1-0.2 , also CVS Head
+	* mISDN/mISDNuser (3.0-beta) from isdn.jolly.de
+
+
+Known Problems
+--------------
+
+* When I use mISDN->IAX I cannot make Trunk calls
+
+-> You need to use ztdummy as dummy zaptel interface for the iax timing in
+trunking mode, simply grab libpri, zaptel and compile them (i think you need
+to modify the makefile in zaptel to add ztdummy to the defaultly compiled
+modules) then modprobe ztdummy, this resolves the problem.
+
+
+* I cannot hear any tone after succesfull CONNECT to other end
+
+-> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching
+and dtmf tone detection
+
+* I have strange ISDN behavior: sometimes I hear the other end, sometimes
+not. also i get STATUS Events with cause 100, with misdn debugging
+
+-> Please update to newest version of chan_misdn and set the te_choose_channel
+option in misdn.conf to yes
+
+Changes
+-------
+
+in the Changes File
+