doc/misdn.txt

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