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