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