Making these documentation changes in the 1.4 branch upset various people, so

these chanes will only be done in the trunk.


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.4@58955 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 291 insertions, 0 deletions

diff --git a/doc/misdn.txt b/doc/misdn.txt
new file mode 100644
index 000000000..74f9742fb
--- /dev/null
+++ b/doc/misdn.txt
@@ -0,0 +1,291 @@
+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)
+* Hardware Bridging
+* DTMF Detection in HW+mISDNdsp 
+* Display Messages on Phones (on those that support display msg)
+* app_SendText
+* HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
+* Screen/ Not Screen User Number
+* EchoCancellation 
+* Volume Control 
+* Crypting with mISDNdsp (Blowfish)
+* Data (HDLC) callthrough 
+* Data Calling (with app_ptyfork +pppd)
+* Echo cancellation
+* CallDeflection
+* Some other
+
+Supported Hardware:
+-------------------
+
+chan_misdn supports any mISDN compatible Hardware.
+
+Overview
+--------
+
+- Fast Installation Guide
+- Pre-Requisites
+- Configuration
+- Dial and Options String
+- misdn cli commands
+- mISDN Variables
+- Debugging and sending Bugreports
+- Examples
+- Known Problems
+- Changes
+
+
+Fast Installation Guide
+-----------------------
+
+It is easy to install mISDN and mISDNuser. Just fetch the newest head of the
+cvs, this can be done by:
+
+cvs -d:pserver:anonymous:readonly@cvs.isdn4linux.de:/i4ldev co mISDN mISDNuser
+
+the compile and install both with:
+
+cd mISDN ;
+make && make install
+
+(you will need at least your kernel headers to compile mISDN).
+
+cd mISDNuser ;
+make && make install
+
+Now you can compile chan_misdn, just by making asterisk: 
+
+cd asterisk ; 
+make && make install
+
+That's all!
+
+
+Follow the instructions in the mISDN Package for howto loading the Kernel
+Modules.
+
+Pre-Requisites
+--------------
+
+To compile and install this driver, you'll need at least one mISDN Driver and
+the mISDNuser package. Chan_misdn works with both, the current release version
+and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must
+be fetched from cvs.isdn4linux.de.
+
+You should use Kernels >= 2.6.9 
+
+
+Configuration
+-------------
+
+First of all you must configure the mISDN drivers, please follow the
+instructions in the mISDN package to do that, the main config file and config
+script is:
+
+/etc/init.d/misdn-init  and
+/etc/misdn-init.conf
+
+
+Now you will want to configure the misdn.conf file which resides in the
+asterisk config directory (normally /etc/asterisk).
+
+- misdn.conf: [general]
+The misdn.conf file contains a "general" Section, and user sections which
+contain misdn port settings and different Asterisk contexts.
+
+In the general Section you can set options that are not directly port
+related. There is for example the very important debug variable which you can
+set from the Asterisk cli (command line interface) or in this configuration
+file, bigger numbers will lead to more debug output. There's also a tracefile
+option, which takes a path+filename where debug output is written to.
+
+- misdn.conf: [default] section 
+
+The default section is another special section which can contain all the
+options available in the user/port sections. the user/port section inherit
+their parameters from the default section.
+
+- misdn.conf: user/port sections
+
+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
+multiple ports, comma separated.
+
+Espacially for TE-Mode Ports there is a msns option. This option tells the
+chan_misdn driver to listen for incoming calls with the given msns, you can
+insert a '*' as single msn, which leads in getting every incoming 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 incoming calls to in the Asterisk dial plan (extension.conf).
+
+
+Dial and Options String
+-----------------------
+
+The dial string of chan_misdn got more complex, because we added more features,
+so the generic dial string looks like:
+
+mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
+
+The Optionsstring looks Like:
+:<optchar1><OptParam1>:<optchar2><OptParam2>
+
+the ":" character is the delimiter.
+
+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 cancellation 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 dial plan 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 current ports, their 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 an Asterisk channel is created and
+isdn is in the correct state. "correct state" means that you have established a
+call to another phone (mustn't 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.
+
+
+mISDN Variables
+---------------
+
+mISDN Exports/Imports a few Variables: 
+
+- MISDN_ADDRESS_COMPLETE : 	Is either set to 1 from the Provider, or you 
+				can set it to 1 to force a sending complete.
+
+
+
+Debugging and sending bug reports
+---------------------------------
+
+If you encounter problems, you should set up the debugging flag, usually
+debug=2 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 open a report in the Asterisk issue
+tracker at http://bugs.digium.com in the "channel drivers" project,
+"chan_misdn" category. Read the bug guidelines to make sure you
+provide all the information needed.
+
+
+Examples
+--------
+
+Here are 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)
+
+On the last line, you will notice the last argument (Hello); this is sent
+as Display Message to the Phone.
+
+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 default compiled
+modules) then modprobe ztdummy, this resolves the problem.
+
+
+* I cannot hear any tone after a successful CONNECT to the other end
+
+-> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching
+and dtmf tone detection
+
+
+Changes
+-------
+in the Changes File
+