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