Merged revisions 7265-7266,7268-7275 via svnmerge from
[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 * Some other
25
26 Supported Hardware:
27 -------------------
28
29 chan_misdn supports any mISDN compatible Hardware. Especially the 1-8 Port
30 BRI Cards available from http://shop.beronet.com
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 You have two options on how to install chan_misdn.
53
54 (1) Requirements: 
55       - mISDN and mISDNuser from jolly (see Pre-Requisites below)
56     Installation: 
57           - cd <asterisk-src-dir>/channels/misdn
58           - edit Makefile so that MISDNUSER points to your mISDNuser directory
59           - run 'make'
60           - cd <asterisk-src-dir>
61           - compile and install asterisk via 'make install'
62
63 (2) Requirements:
64       - Asterisk headers and Kernel headers
65     Description:
66       The Makefile gets the newest mISDN and mISDNuser Sources from 
67           jollys webpage and the newest release of chan_misdn from beronets 
68           Servers. After that it compiles and installs everything (hopefully).
69     Installation:
70       - cd /usr/src
71       - wget http://www.beronet.com/downloads/install-misdn.tar.gz
72           - tar zxf install-misdn.tar.gz
73           - cd install-misdn
74           - make install
75
76
77 Pre-Requisites
78 --------------
79
80 To compile and install this driver, you'll need at least one mISDN Driver, the
81 mISDNuser package and the Asterisk includes (which will be inside of the
82 sources). Chan_misdn works with both, the current release version and the 
83 development (svn trunk) version of Asterisk.
84
85 To get the mISDN stuff please follow the instructions at
86 http://www.isdn4linux.de.  Please Note that mISDN works good for the
87 linux-2.6.x kernels. Some of the mISDN drivers do not compile against the
88 2.4.x or older kernels, you can patch them, but than you'll get mysterious
89 errors.
90
91 I use Kernels > 2.6.9 and it works perfect. with kernels >= 2.6.10 there is a
92 very litle bug in hfc_multi.c which causes the module not to compile, it can
93 be easily fixed by changing pci_findsubsys to pci_getsubsys in code.
94
95 Ok so far so good, now follow the compilation instructions.
96
97 !! Dont forget to create the /dev/mISDN device node.
98
99 Compilation 
100 -----------
101
102 !! Be aware, in the actual mISDNuser package theres a bug in the Makefile
103 !! the compilation stops near iapplication.h, this isn't very important
104 !! at this step you are ready. 
105
106 After you've successfully installed mISDN, mISDNuser and Asterisk, you should
107 modify the Makefile in the chan_misdn source path. There you can tell the
108 Makefile where to install the driver, sample-conf, and most important where it
109 can find the linux kernel includes, the mISDNuser package and the Asterisk
110 includes.  If you use the development version of Asterisk (or at least a newer
111 version than release) uncomment the CCFLAGS+=-DASTERISK_STABLE, the release
112 version of Asterisk is at the moment v1-2 as subversion branch.
113
114 Now you can type in: 
115
116 make
117
118 This should compile chan_misdn.so, if there's an error check the paths in the
119 Makefile again.
120
121
122 Installation
123 ------------
124
125 After successful compilation of chan_misdn, you should simply type in:
126
127 make install 
128
129 as privileged user to put chan_misdn.so in the Asterisk modules
130 directory.
131
132 You should see a message like: "Successfully installed chan_misdn". 
133 Congratulations. 
134
135 Theres a sample init.d script for loading the mISDN modules (mISDN.sample),
136 simply copy it to /etc/init.d/ and modify it, there you can enter your cards.
137
138 !! Forget to use capi together with chan_misdn. 
139
140
141
142 Configuration
143 -------------
144
145 First of all you must configure the mISDN drivers. Each driver module has got
146 an options and layermask option, which tells the driver wether to start in
147 TE, NT, PP or PMP mode (there are lots more, please read docs in misdn for
148 that).
149
150 After thinking about the above you'll probably want to configure the
151 misdn.conf file which resides in the asterisk config directory (normally
152 /etc/asterisk).
153
154 - misdn.conf: [general]
155 The misdn.conf file contains a "general" Section, and user sections which
156 contain misdn port settings and different Asterisk contexts.
157
158 The general section contains especially a variable named context with which
159 the default context is set. There is also the very important debug variable
160 which you can set from the Asterisk cli (command line interface) or in this
161 configuration file, bigger numbers will lead to more debug output. There's also a
162 tracefile option, which takes a path+filename where debug output is written
163 to.
164
165 - misdn.conf: user/port sections
166 The user sections have names which are unequal to "general". Those sections
167 contain the ports variable which mean the mISDN Ports. Here you can add
168 multiple ports, comma separated. 
169
170 Espacially for TE-Mode Ports there is a msns variable. This variable tells the
171 chan_misdn driver to listen for incomming calls with the given msns, you can
172 insert a '*' as single msn, which leads in getting every incoming call (if
173 you want to share on PMP TE S0 with a asterisk and a phone or isdn card you
174 should insert here the msns which you'll like to give the Asterisk).  Finally
175 a context variable resides in the user sections, which tells chan_misdn where
176 to send incoming calls to in the Asterisk dial plan (extension.conf).
177
178 In NT-Mode Ports there is a new option, directly after the port number you can
179 write ptp, this enables PP Mode for this port, please look at misdn.conf.sample for
180 an example.
181
182
183 Dial and Options String
184 -----------------------
185
186 The dial string of chan_misdn got more complex, because we added more features,
187 so the generic dial string looks like:
188
189 mISDN/<port>|g:<group>/<extension>[/<OPTIONSSTRING>]
190
191 The Optionsstring looks Like:
192 :<optchar1><OptParam1>:<optchar2><OptParam2>
193
194 the ":" character is the delimiter.
195
196 The available Optchars are: 
197         d - Send display text on called phone, text is the optparam
198         n - don't detect dtmf tones on called channel
199         h - make digital outgoing call
200         c - make crypted outgoing call, param is keyindex
201         e - perform echo cancelation on this channel, 
202             takes taps as arguments (32,64,128,256)
203         s - send Non Inband DTMF as inband
204         vr - rxgain control
205         vt - txgain control
206
207
208 chan_misdn registers a new dial plan application "misdn_set_opt" when loaded. This 
209 application takes the Optionsstring as argument. The Syntax is:
210
211 misdn_set_opt(<OPTIONSSTRING>)
212
213
214 When you set options in the dialstring, the options are set in the external
215 channel. When you set options with misdn_set_opt, they are set in the current
216 incoming channel. So if you like to use static encryption, the scenario looks
217 as follows:
218
219 Phone1 --> * Box 1 --> PSTN_TE 
220 PSTN_TE --> * Box 2 --> Phone2
221
222 The Encryption must be done on the PSTN sides, so the dialplan on the boxes
223 are:
224
225 * Box 1:
226 exten => _${CRYPT_PREFIX}X.,1,Dial(mISDN/g:outbound/:c1)
227
228 * Box 2:
229 exten => ${CRYPT_MSN},1,misdn_set_opt(:c1)
230 exten => ${CRYPT_MSN},2,dial(${PHONE2})
231
232
233
234
235 misdn cli commands
236 ------------------
237
238 At the Asterisk cli you can try to type in: 
239
240 misdn <tab> <tab>
241
242 Now you should see the misdn cli commands: 
243
244 - clean
245         -> pid          (cleans a broken call, use with care, leads often
246                          to a segmentation fault)
247 - send
248         -> display      (sends a Text Message to a Asterisk channel, 
249                          this channel must be an misdn channel)
250 - set
251         -> debug        (sets debug level)
252 - show
253         -> config       (shows the configuration options)
254         -> channels     (shows the current active misdn channels)
255         -> channel      (shows details about the given misdn channels)
256         -> stacks       (shows the currend ports, there protocols and states)
257         -> fullstacks   (shows the current active and inactive misdn channels)
258
259 - restart 
260         -> port         (restarts given port (L2 Restart) )
261
262 - reload                (reloads misdn.conf)
263
264 You can only use "misdn send display" when an Asterisk channel is created and
265 isdn is in the correct state. "correct state" means that you have established a
266 call to another phone (mustn't be isdn though).
267
268 Then you use it like this:
269
270 misdn send display mISDN/1/101 "Hello World!"
271
272 where 1 is the Port of the Card where the phone is plugged in, and 101 is the
273 msn (callerid) of the Phone to send the text to.
274
275
276
277 Debugging and sending bug reports
278 ---------------------------------
279
280 If you encounter problems, you should set up the debugging flag, usually debug=1 
281 should be enough. the messages are divided in asterisk and misdn parts. 
282 Misdn Debug messages begin with an 'I', asterisk messages begin with an '*', 
283 the rest is clear I think. 
284
285 Please take a trace of the problem and open a report in the Asterisk issue
286 tracker at http://bugs.digium.com in the "channel drivers" project,
287 "chan_misdn" category. Read the bug guidelines to make sure you
288 provide all the information needed.
289
290
291 Examples
292 --------
293
294 Here are some examples of how to use chan_misdn in the dialplan (extensions.conf): 
295
296
297 [globals]
298 OUT_PORT=1 ; The physical Port of the Card
299 OUT_GROUP=ExternE1 ; The Group of Ports defined in misdn.conf
300
301 [misdnIn]
302 exten => _X.,1,Dial(mISDN/${OUT_PORT}/${EXTEN})
303 exten => _0X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1})
304 exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello)
305 exten => _1X.,1,Dial(mISDN/g:${OUT_GROUP}/${EXTEN:1}/:dHello Test:n)
306
307 In the last line you will notice the last argument (Hello), this is sended
308 as Display Message to the Phone.
309
310
311 Known working configurations
312 ----------------------------
313
314 In this section I'll put working configurations for chan_misdn. Beware It
315 seems that between Kernel 2.6.3 and Kernel 2.6.8 there were lots of mISDN
316 Bugs. I use Kernel 2.6.9 now, it works quite ok, Kernel 2.6.10+ has changed
317 the pci_find_subgsys funktion, so hfc_multi from mISDN doesn't compile against
318 it, you can just change pci_find_subsys to pci_get_subsys, this works.
319
320
321 - chan_misdn-0.0.3-rc1:         
322         * linux-kernel >= 2.6.3 (but at least 2.6) 
323         * asterisk >= v1-0 
324         * mISDN/mISDNuser since September/04
325
326 - chan_misdn-0.0.3-rc3:         
327         * linux-kernel >= 2.6.3 (but at least 2.6) 
328         * asterisk >= v1-0.2 
329         * mISDN/mISDNuser since December/04
330
331 - chan_misdn-0.0.3-rc4:         
332         * linux-kernel >= 2.6.8 (but at least 2.6) 
333         * asterisk >= v1-0.2 
334         * mISDN/mISDNuser head on cvs.isdn4linux.de
335
336 - chan_misdn-0.0.3-rc6:         
337         * linux-kernel >= 2.6.8 (but at least 2.6) 
338         * asterisk >= v1-0.2 
339         * mISDN/mISDNuser head on cvs.isdn4linux.de
340
341 - chan_misdn-0.1.0
342         * linux-kernel >= 2.6.8 (but at least 2.6) 
343         * asterisk >= v1-0.2 , also CVS Head
344         * mISDN/mISDNuser (3.0-beta) from isdn.jolly.de
345
346
347 Known Problems
348 --------------
349
350 * When I use mISDN->IAX I cannot make Trunk calls
351
352 -> You need to use ztdummy as dummy zaptel interface for the iax timing in
353 trunking mode, simply grab libpri, zaptel and compile them (i think you need
354 to modify the makefile in zaptel to add ztdummy to the defaultly compiled
355 modules) then modprobe ztdummy, this resolves the problem.
356
357
358 * I cannot hear any tone after succesfull CONNECT to other end
359
360 -> you forgot to load mISDNdsp, which is now needed by chan_misdn for switching
361 and dtmf tone detection
362
363 * I have strange ISDN behavior: sometimes I hear the other end, sometimes
364 not. Also I get STATUS Events with cause 100, with misdn debugging
365
366 -> Please update to newest version of chan_misdn and set the te_choose_channel
367 option in misdn.conf to yes
368
369 Changes
370 -------
371 in the Changes File
372