1 files changed, 272 insertions, 0 deletions
diff --git a/trunk/doc/tex/misdn.tex b/trunk/doc/tex/misdn.tex
new file mode 100644
index 000000000..84dbb7aaa
--- /dev/null
+++ b/trunk/doc/tex/misdn.tex
@@ -0,0 +1,272 @@
+\subsection{Introduction}
+
+This package contains the mISDN Channel Driver for the Asterisk PBX. It
+supports every mISDN Hardware and provides an interface for asterisk.
+
+\subsection{Features}
+
+\begin{itemize}
+\item  NT and TE mode
+\item  PP and PMP mode
+\item  BRI and PRI (with BNE1 and BN2E1 Cards)
+\item  Hardware Bridging
+\item  DTMF Detection in HW+mISDNdsp
+\item  Display Messages on Phones (on those that support display msg)
+\item  app\_SendText
+\item  HOLD/RETRIEVE/TRANSFER on ISDN Phones : )
+\item  Screen/ Not Screen User Number
+\item  EchoCancellation
+\item  Volume Control
+\item  Crypting with mISDNdsp (Blowfish)
+\item  Data (HDLC) callthrough
+\item  Data Calling (with app\_ptyfork +pppd)
+\item  Echo cancellation
+\item  CallDeflection
+\item Some other
+\end{itemize}
+
+\subsection{Fast Installation Guide}
+
+It is easy to install mISDN and mISDNuser. This can be done by:
+\begin{itemize}
+     \item You can download latest stable releases from \url{http://www.misdn.org/downloads/}
+
+     \item Just fetch the newest head of the GIT (mISDN provect moved from CVS)
+     In details this process described here: \url{http://www.misdn.org/index.php/GIT}
+\end{itemize}
+
+
+then compile and install both with:
+\begin{astlisting}
+\begin{verbatim}
+cd mISDN ;
+make && make install
+\end{verbatim}
+\end{astlisting}
+(you will need at least your kernel headers to compile mISDN).
+\begin{astlisting}
+\begin{verbatim}
+cd mISDNuser ;
+make && make install
+\end{verbatim}
+\end{astlisting}
+Now you can compile chan\_misdn, just by making asterisk:
+\begin{astlisting}
+\begin{verbatim}
+cd asterisk ;
+./configure && make && make install
+\end{verbatim}
+\end{astlisting}
+That's all!
+
+Follow the instructions in the mISDN Package for how to load the Kernel
+Modules. Also install process described in \url{http://www.misdn.org/index.php/Installing_mISDN}
+
+\subsection{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
+
+
+\subsection{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:
+\begin{astlisting}
+\begin{verbatim}
+/etc/init.d/misdn-init  and
+/etc/misdn-init.conf
+\end{verbatim}
+\end{astlisting}
+Now you will want to configure the misdn.conf file which resides in the
+asterisk config directory (normally /etc/asterisk).
+
+\subsubsection{misdn.conf: [general]}
+The misdn.conf file contains a "general" subsection, and user subsections which
+contain misdn port settings and different Asterisk contexts.
+
+In the general subsection 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.
+
+\subsubsection{misdn.conf: [default] subsection}
+
+The default subsection is another special subsection which can contain all the
+options available in the user/port subsections. the user/port subsection inherit
+their parameters from the default subsection.
+
+\subsubsection{misdn.conf: user/port subsections}
+
+The user subsections have names which are unequal to "general". Those subsections
+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 subsections, which tells chan\_misdn where to
+send incoming calls to in the Asterisk dial plan (extension.conf).
+
+
+\subsubsection{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:
+
+\begin{astlisting}
+\begin{verbatim}
+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
+\end{verbatim}
+\end{astlisting}
+
+chan\_misdn registers a new dial plan application "misdn\_set\_opt" when
+loaded. This application takes the Optionsstring as argument. The Syntax is:
+
+\begin{verbatim}
+misdn_set_opt(<OPTIONSSTRING>)
+\end{verbatim}
+
+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:
+
+\begin{verbatim}
+Phone1 --> * Box 1 --> PSTN_TE
+PSTN_TE --> * Box 2 --> Phone2
+\end{verbatim}
+
+The Encryption must be done on the PSTN sides, so the dialplan on the boxes
+are:
+
+\begin{verbatim}
+* 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})
+\end{verbatim}
+
+
+\subsection{mISDN CLI commands}
+
+At the Asterisk cli you can try to type in:
+
+\begin{verbatim}
+misdn <tab> <tab>
+\end{verbatim}
+
+Now you should see the misdn cli commands:
+
+\begin{astlisting}
+\begin{verbatim}
+- 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)
+\end{verbatim}
+\end{astlisting}
+
+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.
+
+\subsection{mISDN Variables}
+
+mISDN Exports/Imports a few Variables:
+
+\begin{verbatim}
+- MISDN_ADDRESS_COMPLETE :  Is either set to 1 from the Provider, or you
+        can set it to 1 to force a sending complete.
+\end{verbatim}
+
+
+\subsection{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 \url{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.
+
+
+\subsection{Examples}
+
+Here are some examples of how to use chan\_misdn in the dialplan
+(extensions.conf):
+
+\begin{astlisting}
+\begin{verbatim}
+[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)
+\end{verbatim}
+\end{astlisting}
+
+On the last line, you will notice the last argument (Hello); this is sent
+as Display Message to the Phone.
+
+\subsection{Known Problems}
+
+Q: I cannot hear any tone after a successful CONNECT to the other end
+
+A: You forgot to load mISDNdsp, which is now needed by chan\_misdn for switching
+and dtmf tone detection