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