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