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