doc/tex/misdn.tex

   1 \subsection{Introduction}
   2
   3 This package contains the mISDN Channel Driver for the Asterisk PBX. It
   4 supports every mISDN Hardware and provides an interface for Asterisk.
   5
   6 \subsection{Features}
   7
   8 \begin{itemize}
   9 \item NT and TE mode
  10 \item PP and PMP mode
  11 \item BRI and PRI (with BNE1 and BN2E1 Cards)
  12 \item Hardware bridging
  13 \item DTMF detection in HW+mISDNdsp
  14 \item Display messages on phones (on those that support it)
  15 \item app\_SendText
  16 \item HOLD/RETRIEVE/TRANSFER on ISDN phones : )
  17 \item Allow/restrict user number presentation
  18 \item Volume control
  19 \item Crypting with mISDNdsp (Blowfish)
  20 \item Data (HDLC) callthrough
  21 \item Data calling (with app\_ptyfork +pppd)
  22 \item Echo cancellation
  23 \item Call deflection
  24 \item Some others
  25 \end{itemize}
  26
  27 \subsection{Fast Installation Guide}
  28
  29 It is easy to install mISDN and mISDNuser. This can be done by:
  30 \begin{itemize}
  31      \item You can download latest stable releases from \url{http://www.misdn.org/downloads/}
  32
  33      \item Just fetch the newest head of the GIT (mISDN project moved from CVS)
  34      In details this process described here: \url{http://www.misdn.org/index.php/GIT}
  35 \end{itemize}
  36
  37
  38 then compile and install both with:
  39 \begin{astlisting}
  40 \begin{verbatim}
  41 cd mISDN ;
  42 make && make install
  43 \end{verbatim}
  44 \end{astlisting}
  45 (you will need at least your kernel headers to compile mISDN).
  46 \begin{astlisting}
  47 \begin{verbatim}
  48 cd mISDNuser ;
  49 make && make install
  50 \end{verbatim}
  51 \end{astlisting}
  52 Now you can compile chan\_misdn, just by making Asterisk:
  53 \begin{astlisting}
  54 \begin{verbatim}
  55 cd asterisk ;
  56 ./configure && make && make install
  57 \end{verbatim}
  58 \end{astlisting}
  59 That's all!
  60
  61 Follow the instructions in the mISDN Package for how to load the Kernel
  62 Modules. Also install process described in \url{http://www.misdn.org/index.php/Installing_mISDN}
  63
  64 \subsection{Pre-Requisites}
  65
  66 To compile and install this driver, you'll need at least one mISDN Driver and
  67 the mISDNuser package. Chan\_misdn works with both, the current release version
  68 and the development (svn trunk) version of Asterisk. mISDNuser and mISDN must
  69 be fetched from cvs.isdn4linux.de.
  70
  71 You should use Kernels $>$= 2.6.9
  72
  73
  74 \subsection{Configuration}
  75
  76 First of all you must configure the mISDN drivers, please follow the
  77 instructions in the mISDN package to do that, the main config file and config
  78 script is:
  79 \begin{astlisting}
  80 \begin{verbatim}
  81 /etc/init.d/misdn-init  and
  82 /etc/misdn-init.conf
  83 \end{verbatim}
  84 \end{astlisting}
  85 Now you will want to configure the misdn.conf file which resides in the
  86 Asterisk config directory (normally /etc/asterisk).
  87
  88 \subsubsection{misdn.conf: [general]}
  89 The misdn.conf file contains a "general" subsection, and user subsections which
  90 contain misdn port settings and different Asterisk contexts.
  91
  92 In the general subsection you can set options that are not directly port
  93 related. There is for example the very important debug variable which you can
  94 set from the Asterisk cli (command line interface) or in this configuration
  95 file, bigger numbers will lead to more debug output. There's also a trace file
  96 option, which takes a path+filename where debug output is written to.
  97
  98 \subsubsection{misdn.conf: [default] subsection}
  99
 100 The default subsection is another special subsection which can contain all the
 101 options available in the user/port subsections. The user/port subsections inherit
 102 their parameters from the default subsection.
 103
 104 \subsubsection{misdn.conf: user/port subsections}
 105
 106 The user subsections have names which are unequal to "general". Those subsections
 107 contain the ports variable which mean the mISDN Ports. Here you can add
 108 multiple ports, comma separated.
 109
 110 Especially for TE-Mode Ports there is a msns option. This option tells the
 111 chan\_misdn driver to listen for incoming calls with the given msns, you can
 112 insert a '*' as single msn, which leads to getting every incoming call. If you
 113 want to share on PMP TE S0 with Asterisk and a phone or ISDN card you should
 114 insert here the msns which you assign to Asterisk.  Finally a context variable
 115 resides in the user subsections, which tells chan\_misdn where to send incoming
 116 calls to in the Asterisk dial plan (extension.conf).
 117
 118
 119 \subsubsection{Dial and Options String}
 120
 121 The dial string of chan\_misdn got more complex, because we added more features,
 122 so the generic dial string looks like:
 123
 124 \begin{astlisting}
 125 \begin{verbatim}
 126 mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
 127
 128 The Optionsstring looks Like:
 129 :<optchar><optarg>:<optchar><optarg>...
 130
 131 the ":" character is the delimiter.
 132
 133 The available options are:
 134   a - Have Asterisk detect DTMF tones on called channel
 135   c - Make crypted outgoing call, optarg is keyindex
 136   d - Send display text to called phone, text is the optarg
 137   e - Perform echo cancelation on this channel,
 138       takes taps as optarg (32,64,128,256)
 139  e! - Disable echo cancelation on this channel
 140   f - Enable fax detection
 141   h - Make digital outgoing call
 142  h1 - Make HDLC mode digital outgoing call
 143   i - Ignore detected DTMF tones, don't signal them to Asterisk,
 144       they will be transported inband.
 145  jb - Set jitter buffer length, optarg is length
 146  jt - Set jitter buffer upper threshold, optarg is threshold
 147  jn - Disable jitter buffer
 148   n - Don't have mISDN detect DTMF tones on called channel
 149   p - Caller ID presentation,
 150       optarg is either 'allowed' or 'restricted'
 151   s - Send Non-inband DTMF as inband
 152  vr - Rx gain control, optarg is gain
 153  vt - Tx gain control, optarg is gain
 154 \end{verbatim}
 155 \end{astlisting}
 156
 157 chan\_misdn registers a new dial plan application "misdn\_set\_opt" when
 158 loaded. This application takes the Optionsstring as argument. The Syntax is:
 159
 160 \begin{verbatim}
 161 misdn_set_opt(<OPTIONSSTRING>)
 162 \end{verbatim}
 163
 164 When you set options in the dialstring, the options are set in the external
 165 channel. When you set options with misdn\_set\_opt, they are set in the current
 166 incoming channel. So if you like to use static encryption, the scenario looks
 167 as follows:
 168
 169 \begin{verbatim}
 170 Phone1 --> * Box 1 --> PSTN_TE
 171 PSTN_TE --> * Box 2 --> Phone2
 172 \end{verbatim}
 173
 174 The encryption must be done on the PSTN sides, so the dialplan on the boxes
 175 are:
 176
 177 \begin{verbatim}
 178 * Box 1:
 179 exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)
 180
 181 * Box 2:
 182 exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
 183 exten => ${CRYPT_MSN},2,dial(${PHONE2})
 184 \end{verbatim}
 185
 186
 187 \subsection{mISDN CLI commands}
 188
 189 At the Asterisk cli you can try to type in:
 190
 191 \begin{verbatim}
 192 misdn <tab> <tab>
 193 \end{verbatim}
 194
 195 Now you should see the misdn cli commands:
 196
 197 \begin{astlisting}
 198 \begin{verbatim}
 199 - clean
 200   -> pid    (cleans a broken call, use with care, leads often
 201        to a segmentation fault)
 202 - send
 203   -> display  (sends a Text Message to a Asterisk channel,
 204        this channel must be an misdn channel)
 205 - set
 206   -> debug  (sets debug level)
 207 - show
 208   -> config (shows the configuration options)
 209   -> channels (shows the current active misdn channels)
 210   -> channel  (shows details about the given misdn channels)
 211   -> stacks (shows the current ports, their protocols and states)
 212   -> fullstacks (shows the current active and inactive misdn channels)
 213
 214 - restart
 215   -> port   (restarts given port (L2 Restart) )
 216
 217 - reload    (reloads misdn.conf)
 218 \end{verbatim}
 219 \end{astlisting}
 220
 221 You can only use "misdn send display" when an Asterisk channel is created and
 222 isdn is in the correct state. "correct state" means that you have established a
 223 call to another phone (mustnot be isdn though).
 224
 225 Then you use it like this:
 226
 227 misdn send display mISDN/1/101 "Hello World!"
 228
 229 where 1 is the Port of the Card where the phone is plugged in, and 101 is the
 230 msn (callerid) of the Phone to send the text to.
 231
 232 \subsection{mISDN Variables}
 233
 234 mISDN Exports/Imports a few Variables:
 235
 236 \begin{verbatim}
 237 - MISDN_ADDRESS_COMPLETE :  Is either set to 1 from the Provider, or you
 238         can set it to 1 to force a sending complete.
 239 \end{verbatim}
 240
 241
 242 \subsection{Debugging and sending bug reports}
 243
 244 If you encounter problems, you should set up the debugging flag, usually
 245 debug=2 should be enough. The messages are divided into Asterisk and mISDN
 246 parts.  mISDN Debug messages begin with an 'I', Asterisk messages begin with
 247 an '*', the rest is clear I think.
 248
 249 Please take a trace of the problem and open a report in the Asterisk issue
 250 tracker at \url{http://bugs.digium.com} in the "channel drivers" project,
 251 "chan\_misdn" category. Read the bug guidelines to make sure you
 252 provide all the information needed.
 253
 254
 255 \subsection{Examples}
 256
 257 Here are some examples of how to use chan\_misdn in the dialplan
 258 (extensions.conf):
 259
 260 \begin{astlisting}
 261 \begin{verbatim}
 262 [globals]
 263 OUT_PORT=1 ; The physical Port of the Card
 264 OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
 265
 266 [misdnIn]
 267 exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN})
 268 exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
 269 exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
 270 exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)
 271 \end{verbatim}
 272 \end{astlisting}
 273
 274 On the last line, you will notice the last argument (Hello); this is sent
 275 as Display Message to the Phone.
 276
 277 \subsection{Known Problems}
 278
 279 Q: I cannot hear any tone after a successful CONNECT to the other end.
 280
 281 A: You forgot to load mISDNdsp, which is now needed by chan\_misdn for switching
 282 and DTMF tone detection.