Add perldoc for twinstar.

This also avoids a bogus, empty twinstar.8 man page.

Merged revisions 7219,7263 via svnmerge from 
http://svn.digium.com/svn/dahdi/tools/trunk

........
  r7219 | tzafrir | 2009-09-27 13:49:40 +0200 (Sun, 27 Sep 2009) | 5 lines
  
  xpp: install twinstar by default; Add a man page
  
  Add a man page to twinstar (as perl POD) and get it installed by
  default.
........
  r7263 | tzafrir | 2009-09-29 22:45:50 +0200 (Tue, 29 Sep 2009) | 2 lines
  
  xpp: fix a typo in documentation
........


git-svn-id: http://svn.asterisk.org/svn/dahdi/tools/branches/2.2@7805 a0bf4364-ded3-4de4-8d8a-66a801d63aff

1 files changed, 102 insertions, 0 deletions

diff --git a/xpp/twinstar b/xpp/twinstar
index b5e43ff..3b36f6f 100755
--- a/xpp/twinstar
+++ b/xpp/twinstar
@@ -19,6 +19,14 @@ use Dahdi::Xpp;
 use Dahdi::Xpp::Xbus;
 use Dahdi::Xpp::Mpp;
 
+$Getopt::Std::STANDARD_HELP_VERSION = 1;
+$main::VERSION = '$Id$';
+
+sub HELP_MESSAGE() {
+	eval(usage());
+	return 0;
+}
+
 sub usage {
 	die "Usage: $0 {status|jump|enable-wd|disable-wd|ports}\n";
 }
@@ -158,3 +166,97 @@ if($ARGV[0] eq 'status') {
 }
 
 __END__
+
+=head1 NAME
+
+twinstar - Control the Twinstar feature of a Xorcom Astribank
+
+=head1 SYNOPSIS
+
+twinstar {status|jump|enable-wd|disable-wd|ports}
+
+=head1 DESCRIPTION
+
+B<twinstar> is a tool to control the Twinstar (dual USB port) of a
+Xorcom Astribank. There is a single and mandatory argument which is the
+command to run. That command operates on all the Astribanks connected to
+the system.
+
+Technically all the commands are implemented using Dahdi::Xpp::Mpp which
+in turn uses astribank_tool. Thus using thus tool will require root
+permissions or otherwise read/write permissions to the USB device.
+
+The twinstar may be in I<watchdog mode>, which means that it will jump
+to the remote host if it loses contact with the local host. This can
+happen if the machine is powered down or hangs or even if the xpp
+drivers are unloaded. Which is why the standard twinstar scripts put the
+Astribanks in twinstar mode on startup and remove it on normal shutdown.
+
+An Astribank will only jump to the other host (either if asked
+explicitly or by the watchdog) only if there is a different Astribank
+connected to the other port and running. Which is why all of this has no
+effect on systems that don't need this functionality.
+
+The command are:
+
+=head2 status
+
+Shows the current status of all Astribanks. Note that it only shows
+Astribanks whose current active USB port is the one connected to this
+computer.
+
+Example output:
+
+ DEVICE          PORT       WATCHDOG        POWER0     POWER1
+ usb:001/010     0          on              yes        yes
+ usb:001/011     0          on              yes        yes
+
+For each Astribank on the system that has Twinstar support we get:
+
+=over 4
+
+=item Device
+
+The address of the device. This is the bus address, e.g. the address you 
+see in lsusb / dahdi_hardware.
+
+=item Port
+
+The active USB port on the Astribank. This should be always '0' on the
+master and always 1 on the slave.
+
+=item Watchdog
+
+I<on> if the watchdog is triggered in the Atribank or I<off> otherwise.
+
+=item Power0, Power1
+
+Shows which ports of this Astribank are connected to a USB port of a
+running computer. This only shows whether or not the USB host provides
+power.
+
+=back
+
+=head2 ports
+
+Shows the same 'Port' column of the B<status> command.
+
+=head2 jump
+
+Command all the Astribanks to jump to the other port. This works
+regardless the watchdog mode is enabled or not. But requires that there
+is power on the other port.
+
+=head2 enable-wd
+
+Enables watchdog mode.
+
+=head2 disable-wd
+
+Disables watchdog mode.
+
+=head1 FILES
+
+B<twinstar> mostly uses astribank_tool which in turn mostly uses USB
+files under /dev/bus/usb .
+