Typos. Mostly by Lintian
[dahdi/tools.git] / doc / fxotune.8
1 .TH FXOTUNE "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
2 .SH NAME
3 fxotune \- automatically tune DAHDI FXO channels
4 .SH SYNOPSIS
5 .B fxotune \-i 
6 .I [options]
7 \- detect mode
8
9 .B fxotune \-d
10 .I [ options ]
11 \- dump mode
12
13 .B fxotune \-s
14 .I [ options ]
15 \- Startup mode
16 .SH
17 .SH DESCRIPTION
18 .B fxotune 
19 is a script that fine-tune parameters of the FXO modules of the 
20 card. It has three modes of operation:
21
22 .I Detect mode (\-i):
23 it detects and tunes all the available FXO channels.
24 It writes settings to a configuration file (/etc/fxotune.conf)
25 from which it can be loaded (e.g: at startup) using \-s .
26
27 .I Dump mode (\-d):
28 Runs detection on a single DAHDI channel, and just dumps waveforms to
29 .B fxotune_dump.vals
30 is generated in the current directory.
31
32 .I Startup mode (\-s):
33 fxotune just reads the settings from fxotune.conf into the FXO modules.
34
35 You are advised to run fxotune on all FXO ports you have that support 
36 it and that are connected. Note that the tuning is affected by e.g.
37 the physical parameters of the connection, and thus if it has been 
38 radically changed, you may need to re-run fxotune.
39
40 This program only works for the Digium TDM400P/800P/2400P cards and
41 compatible and the Xorcom Astribank devices. Other cards (notably X100P
42 cards and clones) do not have the hardware to support such tuning.
43
44 The tuning process needs a clear line to do the tuning.  In order to do
45 that, it runs in cycles of the following: sets the line off-hook, dials
46 a dial string (which should set the PSTN provider waiting for the next
47 digit), and then starts tuning. It has a limited amount of time for
48 tuning before the PSTN gives up and gives a busy tone. So after a while
49 it hangs up and starts a new cycle.
50
51 .B fxotune
52 has two operation modes: tune (\-i) and set (\-s). In the tune mode it 
53 generates /etc/fxotune.conf, and in the set mode it merely applies the 
54 parameters from fxotune.conf to device's ports.
55
56 .SH OPTIONS
57 The following options below except \-v (verbose) affect only the
58 detection process and hence apply only to the 
59 .I detect
60 and 
61 .I dump
62 modes.
63
64 In addition, to maintain compatibility with older versions of fxotune,
65 if in detect or dump mode there is a parameter with option before it, it
66 is considered to be the 
67 .I dialstring
68 parameter (\-n).
69
70 .B \-b
71 .I startdev
72 .RS
73 Start tuning from dahdi channel num. \fI startdev\fR: skip all previous
74 channels. By default starting from channel 1.
75
76 In dump mode (\-d) this is the single channel that will be tested.
77 .RE
78
79 .B \-e
80 .I stopdev
81 .RS
82 Tune only up to dahdi channel num. \fI stopdev\fR: skip all previous
83 channels. By default stopping at channel 252.
84
85 In dump mode (\-d) this parameter is ignored.
86 .RE
87
88 .B \-l
89 .I delay-to-silence
90 .RS
91 Time in seconds to wait after dialing the dial-string to get a clear line.
92 The default is 0. 
93 before 
94 .RE
95
96 .B \-m
97 .I silence-good-for
98 .RS
99 Time in seconds which states how long the PSTN will wait after we dialed
100 the dial-string until it starts giving a busy tone. You can test this by
101 connecting an analog phone to the line and dialing.
102
103 The default is 18 (18 seconds). 
104 .RE
105
106 .B \-n
107 .I dial-string
108 .RS
109 Digits to dial to the PSTN in order to get it stop its dialtone and
110 waiting for the next digit. 
111
112 The default is "4" (sending just the digit 4). It should work in most
113 cases. Again, this can be tested by connecting a phone to the PSTN line
114 and dialing the dial-string.
115 .RE
116
117 .B \-t
118 .I detect-type
119 .RS
120 This option allows using the older detection method used by fxotune of
121 Zaptel 1.2. use 
122 .B \-t 1
123 for that older method. whereas
124 .B \-t 2
125 (the default) uses the current method.
126
127 This option only applies to detect mode (\-i).
128 .RE
129
130 .B \-v[vvvv]
131 .RS
132 Sets debugging on. The more v-s, the higher debug level. 
133
134 Note that: \-vv \-v  will actually set debug level to 1 instead of 3.
135 .RE
136
137 .B \-w
138 .I wave-form
139 .RS
140 The default: \-1, for multitone waveform. Alternatively: a frequency of a
141 single tone.
142
143 This option only applies to dump mode (\-d).
144 .RE
145
146
147 .SH EXAMPLES
148 .RS
149 fxotune \-i 9
150 .RE
151 if you need to dial 9 for an external line. If you always get a line, you
152 can simply use any digit.
153 .RE
154
155 .B \-s
156 .RS
157 Load settings from the last test. Used at startup.
158 .RE
159
160 .SH FILES
161 .I /etc/fxotune.conf
162 .RS
163 The configuration file generated by fxotune in detect mode and from which
164 configuration is loaded when 
165 .B \-s
166 is used.
167
168 .SH NOTES
169 Running fxotune takes approximately a minute per port. If you wish to only 
170 run fxotune for several ports, you can use the options \-b and \-e to set a 
171 specific range of ports. Another useful trick is to actually keep asterisk 
172 running, and only "destroy" the dahdi channels you wish to tune (dahdi 
173 destroy channel NNN): other channels will be used by Asterisk, and hence 
174 skipped. This can be useful if you have many FXO ports that are not connected.
175
176 .B fxotune
177 writes immediately to 
178 .B /etc/fxotune.conf
179 so if you stop it half-way, you may get a half-configured system. If you
180 have already tuned your FXO channels and wish to test-run fxotune again, 
181 you are advised to backup /etc/fxotune.conf .
182
183 The default for \-m is 18 seconds. This assumes that you get a clear line 
184 for at least 18 seconds. It is advised that you test that timeout earlier
185 by connecting a phone to the FXO line, dialing 4 (or whatever dial string 
186 you put with \-n) and see how much time of silence you have.
187
188 If you connect your device to a PSTN provider that is not in the US, there
189 is a similar operation you should apply before even getting to fxotune:
190 setting the opermode. The opermode sets a number of country-specific 
191 parameters. For the Digium analog cards this is set through the kernel module 
192 parameter 'opermode' . For the Xorcom Astribank this is set through the 
193 variable 'opermode' in /etc/dahdi/xpp.conf .
194 For valid values of this parameter, see
195 /usr/share/asterisk/init_fxo_modes (FIXME: this has changed and will
196 change. Tzafrir).
197
198 .SH SEE ALSO 
199 dahdi_cfg(8), dahdi_tool(8), dahdi_monitor(8), asterisk(8). 
200
201 .SH AUTHOR 
202 This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
203 Permission is granted to copy, distribute and/or modify this document under 
204 the terms of the GNU General Public License, Version 2 any  
205 later version published by the Free Software Foundation. 
206
207 On Debian systems, the complete text of the GNU General Public 
208 License can be found in /usr/share/common\-licenses/GPL.