dahdi-tools/doc/fxotune.8

.TH FXOTUNE "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
.SH NAME
fxotune \- automatically tune DAHDI FXO channels
.SH SYNOPSIS
.B fxotune \-i 
.I [options]
\- detect mode

.B fxotune \-d
.I [ options ]
\- dump mode

.B fxotune \-s
\- Startup mode
.SH
.SH DESCRIPTION
.B fxotune 
is a script that fine-tune parameters of the FXO modules of the 
card. It has three modes of operation:

.I Detect mode (\-i):
it detects and tunes all the available FXO channels.
It writes settings to a configuration file (/etc/fxotune.conf)
from which it can be loaded (e.g: at startup) using \-s .

.I Dump mode (\-d):
Runs detection on a single DAHDI channel, and just dumps waveforms to
.B fxotune_dump.vals
is generated in the current directory.

.I Startup mode (\-s):
fxotune just reads the settings from fxotune.conf into the FXO modules.

You are advised to run fxotune on all FXO ports you have that support 
it and that are connected. Note that the tunning is affected by e.g.
the physical parameters of the connection, and thus if it has been 
radically changed, you may need to re-run fxotune.

This program only works for the Digium TDM400P/800P/2400P cards and
compatible and the Xorcom Astribank devices. Other cards (notably X100P
cards and clones) do not have the hardware to support such tuning.

The tuning process needs a clear line to do the tuning.  In order to do
that, it runs in cycles of the following: sets the line off-hook, dials
a dial string (which should set the PSTN provider waiting for the next
digit), and then starts tuning. It has a limited ammount of time for
tuning before the PSTN gives up and gives a busy tone. So after a while
it hangs up and starts a new cycle.

.B fxotune
has two operation modes: tune (\-i) and set (\-s). In the tune mode it 
generates /etc/fxotune.conf, and in the set mode it merely applies the 
parameters from fxotune.conf to device's ports.

.SH OPTIONS
The following options below except \-v (verbose) affect only the
detection process and hence apply only to the 
.I detect
and 
.I dump
modes.

In addition, to maintain compatibility with older versions of fxotune,
if in detect or dump mode there is a parameter with option before it, it
is considered to be the 
.I dialstring
parameter (\-n).

.B \-b
.I startdev
.RS
Start tuning from dahdi channel num. \fI startdev\fR: skip all previous
channels. By default starting from channel 1.

In dump mode (\-d) this is the single channel that will be tested.
.RE

.B \-e
.I stopdev
.RS
Tune only up to dahdi channel num. \fI stopdev\fR: skip all previous
channels. By default stopping at channel 252.

In dump mode (\-d) this parameter is ignored.
.RE

.B \-l
.I delay-to-silence
.RS
Time in seconds to wait after dialing the dial-string to get a clear line.
The default is 0. 
before 
.RE

.B \-m
.I silence-good-for
.RS
Time in seconds which states how long the PSTN will wait after we dialed
the dial-string until it starts giving a busy tone. You can test this by
connecting an analog phone to the line and dialing.

The default is 18 (18 seconds). 
.RE

.B \-n
.I dial-string
.RS
Digits to dial to the PSTN in order to get it stop its dialtone and
waiting for the next digit. 

The default is "4" (sending just the digit 4). It should work in most
cases. Again, this can be tested by connecting a phone to the PSTN line
and dialing the dial-string.
.RE

.B \-t
.I detect-type
.RS
This option allows using the older detection method used by fxotune of
Zaptel 1.2. use 
.B \-t 1
for that older method. whereas
.B \-t 2
(the default) uses the current method.

This option only applies to detect mode (\-i).
.RE

.B \-v[vvvv]
.RS
Sets debugging on. The more v-s, the higher debug level. 

Note that: \-vv \-v  will actually set debug level to 1 instead of 3.
.RE

.B \-w
.I wave-form
.RS
The default: \-1, for multitone waveform. Alternatively: a frequency of a
single tone.

This option only applies to dump mode (\-d).
.RE


.SH EXAMPLES
.RS
fxotune \-i 9
.RE
if you need to dial 9 for an external line. If you always get a line, you
can simply use any digit.
.RE

.B \-s
.RS
Load settings from the last test. Used at startup.
.RE

.SH FILES
.I /etc/fxotune.conf
.RS
The configuration file generated by fxotune in detect mode and from which
configuration is loaded when 
.B \-s
is used.

.SH NOTES
Running fxotune takes approximately a minute per port. If you wish to only 
run fxotune for several ports, you can use the options \-b and \-e to set a 
specific range of ports. Another useful trick is to actually keep asterisk 
running, and only "destroy" the dahdi channels you wish to tune (dahdi 
destroy channel NNN): other channels will be used by Asterisk, and hence 
skipped. This can be useful if you have many FXO ports that are not connected.

.B fxotune
writes immediately to 
.B /etc/fxotune.conf
so if you stop it half-way, you may get a half-configured system. If you
have already tuned your FXO channels and wish to test-run fxotune again, 
you are advised to backup /etc/fxotune.conf .

The default for \-m is 18 seconds. This asusmes that you get a clear line 
for at least 18 seconds. It is advised that you test that timeout earlier
by connecting a phone to the FXO line, dialing 4 (or whatever dial string 
you put with \-n) and see how much time of silence you have.

If you connect your device to a PSTN provider that is not in the US, there
is a similar operation you should apply before even getting to fxotune:
setting the opermode. The opermode sets a number of country-specific 
parameters. For the Digium analog cards this is set through the kernel module 
parameter 'opermode' . For the Xorcom Astribank this is set through the 
variable 'opermode' in /etc/dahdi/xpp.conf .
For valid values of this parameter, see
/usr/share/asterisk/init_fxo_modes (FIXME: this has changed and will
change. Tzafrir).

.SH SEE ALSO 
dahdi_cfg(8), dahdi_tool(8), dahdi_monitor(8), asterisk(8). 

.SH AUTHOR 
This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
Permission is granted to copy, distribute and/or modify this document under 
the terms of the GNU General Public License, Version 2 any  
later version published by the Free Software Foundation. 

On Debian systems, the complete text of the GNU General Public 
License can be found in /usr/share/common\-licenses/GPL.