* fxotune man page is up-to-date for 1.4.

* fxtest man page.
(crev. 2611)
* ó is non-printable on non-UTF-8 locales. Replaced with \['o] to make
  lintian happy.
(rev. 2612)



git-svn-id: http://svn.digium.com/svn/zaptel/trunk@2614 5390a7c7-147a-4af0-8ec9-7488f05a26cb

5 files changed, 229 insertions, 26 deletions

diff --git a/doc/fxotune.8 b/doc/fxotune.8
index 2236a70..5f42ee2 100644
--- a/doc/fxotune.8
+++ b/doc/fxotune.8
@@ -1,38 +1,149 @@
-.TH FXOTUNE 8 "September 10th, 2005" "Xorcom Rapid Asterisk" "Linux Programmer's Manual"
+.TH FXOTUNE "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
 .SH NAME
-.B fxotune
-\(em automatically tune FXO channels on a Digium TDM400 card
+fxotune \- automatically tune zaptel FXO channels
 .SH SYNOPSIS
 .B fxotune -i 
-.I <dialstr> 
-\(em detect 
+.I [options]
+- detect mode
 
-.B fxotune -s 
-\(em load settings
+.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 TDM400
-card. Whene run in 
-.I detect
-mode (-i) it detects and tunes all the FXO channels of such cards. It 
-needs a dial string after which the line(s) will give dial tone.
+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 Zaptel 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.
 
-It writes settings to a configuration file (/etc/fxotune.conf , name 
-is hardwired) from which it can be loaded (e.g: at startup) using -s .
+FXOTune 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
-.B -i
+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 zaptel 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 zaptel 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
-.I dialstr
-Start detecting optimal settings.  
-.I dialstr
-Is a number needed to dial to get a dial tone.
-The test can take several minutes, and must be performed when Asterisk
-is not running.
-
-For example: 
+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
@@ -53,6 +164,35 @@ 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 zaptel channels you wish to tune (zap 
+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 immedietly 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/default/zaptel or /etc/sysconfig/zaptel .
+For valid values of this parameter, see
+/usr/share/asterisk/init_fxo_modes .
+
 .SH SEE ALSO 
 ztcfg(8), zttool(8), ztmonitor(8), asterisk(8). 
 
diff --git a/doc/fxstest.8 b/doc/fxstest.8
new file mode 100644
index 0000000..2368dff
--- /dev/null
+++ b/doc/fxstest.8
@@ -0,0 +1,60 @@
+.TH "FXSTEST" "8" "9 June 2007" "asterisk" "System Manager's Manuals: Asterisk"
+
+.SH NAME
+fxstest \- Simple tests for Zaptel FXS adapters
+.SH SYNOPSIS
+
+.B fxstest /dev/zap/\fIN comand\fR
+
+.SH DESCRIPTION
+fxstest can be used to issue one of a number simple tests to FXS
+adapters (analog adapters intended to connect phones). 
+
+.SH OPTIONS
+All of those tests operate on a single zaptel channel which has to be an
+FXS port, and must not be in use by Asterisk or any other program.
+
+The command has two mandatory parameters.
+The first parameter is the device file to operate on. It is typically
+/dev/zap/NN , a device file under /dev/zap .
+
+The second parameter is the name of the command to run on that channel:
+
+.I stats
+.RS
+Reports voltages
+.RE
+
+.I regdump
+.RS
+Dumps ProSLIC registers
+.RE
+
+.I tones
+.RS
+Plays a series of tones
+.RE
+
+.I polarity
+.RS
+Requests channel to reverse polarity.
+.RE
+
+.I ring
+.RS
+Rings phone
+.RE
+
+.SH "SEE ALSO"
+.PP
+zttool(8), ztcfg(8), ztmonitor(8), asterisk(8).
+.SH BUGS
+Does not allow testing channels beyond 249. Should support opening
+channels through /dev/zap/channel .
+.SH AUTHOR
+.PP
+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.
+.PP
diff --git a/doc/ztcfg.8 b/doc/ztcfg.8
index 05cfa0b..29c7051 100644
--- a/doc/ztcfg.8
+++ b/doc/ztcfg.8
@@ -50,7 +50,8 @@ Display a brief help about the usage of \fBztcfg\fR
 zttool(8), ztmonitor(8), asterisk(8).
 .SH "AUTHOR"
 .PP
-This manual page was written by Santiago Ruano Rincón <santiago@unicauca.edu.co> for
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
 the Debian system (but may be used by others).  Permission is
 granted to copy, distribute and/or modify this document under
 the terms of the GNU General Public License, Version 2 any 
diff --git a/doc/ztmonitor.8 b/doc/ztmonitor.8
index 857be65..f217240 100644
--- a/doc/ztmonitor.8
+++ b/doc/ztmonitor.8
@@ -32,7 +32,8 @@ Write output to FILE
 zttool(8), ztcfg(8), asterisk(8).
 .SH "AUTHOR"
 .PP
-This manual page was written by Santiago Ruano Rincón <santiago@unicauca.edu.co> for
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
 the Debian system (but may be used by others).  Permission is
 granted to copy, distribute and/or modify this document under
 the terms of the GNU General Public License, Version 2 any 
diff --git a/doc/zttool.8 b/doc/zttool.8
index 4ab05d0..c3c09d0 100644
--- a/doc/zttool.8
+++ b/doc/zttool.8
@@ -23,7 +23,8 @@ Levels for each Zaptel interface.
 ztmonitor(8), asterisk (8).
 .SH "AUTHOR"
 .PP
-This manual page was written by Santiago Ruano Rincón <santiago@unicauca.edu.co> for
+This manual page was written by Santiago Ruano Rinc\['o]n 
+<santiago@unicauca.edu.co> for
 the Debian system (but may be used by others).  Permission is
 granted to copy, distribute and/or modify this document under
 the terms of the GNU General Public License, Version 2 any