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