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