[dahdi-commits] tzafrir: tools/trunk r7219 - in /tools/trunk/xpp: Makefile twinstar

[SVN commits to the DAHDI project]

Author: tzafrir
Date: Sun Sep 27 06:49:40 2009
New Revision: 7219

URL: http://svnview.digium.com/svn/dahdi?view=rev&rev=7219
Log:
xpp: install twinstar by default; Add a man page

Add a man page to twinstar (as perl POD) and get it installed by
default.

Modified:
    tools/trunk/xpp/Makefile
    tools/trunk/xpp/twinstar

Modified: tools/trunk/xpp/Makefile
URL: http://svnview.digium.com/svn/dahdi/tools/trunk/xpp/Makefile?view=diff&rev=7219&r1=7218&r2=7219
==============================================================================
--- tools/trunk/xpp/Makefile (original)
+++ tools/trunk/xpp/Makefile Sun Sep 27 06:49:40 2009
@@ -49,6 +49,7 @@
 		xpp_blink	\
 		dahdi_genconf	\
 		dahdi_hardware	\
+		twinstar	\
 		#
 
 PERL_MANS	= $(PERL_SCRIPTS:%=%.8)

Modified: tools/trunk/xpp/twinstar
URL: http://svnview.digium.com/svn/dahdi/tools/trunk/xpp/twinstar?view=diff&rev=7219&r1=7218&r2=7219
==============================================================================
--- tools/trunk/xpp/twinstar (original)
+++ tools/trunk/xpp/twinstar Sun Sep 27 06:49:40 2009
@@ -19,6 +19,14 @@
 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";
 }
@@ -161,3 +169,97 @@
 }
 
 __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 just 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 .
+