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