* upstools documentation - Russell Kroll <rkroll@exploits.org>
*
* Version 0.10 - first public release

Program support page: http://www.exploits.org/~rkroll/smartupstools/

How to use the programs, short version

First, a short description of what these binaries do..

 - upsd: daemon.  Talks to the ups via your serial line and answers udp
   queries from clients that arrive via the network.

 - upsmon: daemon.  Talks to upsd and shuts the machine down when the
   battery is low and the line power is gone.  Walls a lot to tell users
   what's going on.

 - upsstats.cgi: user program.  Generates the HTML for the main status page.

 - upsimage.cgi: user program.  Called by IMG SRC tags in status pages.
 
 - upsc: example program.  Shows how to use fetch in your own programs.

OK, assuming you have configured and installed the program already, here
is how you actually use it to keep an eye on things.

A note about the networking capabilities
========================================

Since all the communications between upsd and the clients is UDP based,
they need not live on the same computer.  This design lets you run upsd
on the computer with the serial connection to your UPS, and then run
upsmon on all of the other computers that actually draw power from that UPS.

For example, I have 3 BSD/OS machines at the office that draw power from
one Smart UPS 2200.  One of them has a serial cable going to the UPS, and
runs upsd.  All three run upsmon, and thus monitor the UPS even though they
aren't directly connected.

These networking abilities also let you run the CGI-based stats programs
on a machine that may have nothing to do with your UPS at all, but happens
to be your web server.  

I have somewhat arbitrarily chosen UDP port 3301 for the datagrams.
Since all the client programs use the common upsfetch library to 
retrieve data, changing the port is as simple as changing the two
instances of "3301" in the code and recompiling.

Using upsd
==========

upsd needs to run as much as possible.  For this reason, you should start it
from your system startup scripts.  On Slackware systems, this is as simple
as dumping "/usr/local/ups/upsd" in /etc/rc.d/rc.local.  Similar techniques
apply to other Linux distributions and other operating systems as well.

upsd will use the syslog to tell you when it has started successfully.

Using upsmon
============

upsmon, like upsd, should also run whenever possible.  On a machine that
is to monitor a ups, add a line to your startup scripts to start upsmon.
Such a line might look like "/usr/local/ups/upsmon 1.2.3.4", with your
machine's IP address in place of the 1.2.3.4, obviously.

Using upsstats
==============

upsstats is a CGI program, and as such, you must invoke it through your
web server with a browser.  Assuming you have it installed into your
/cgi-bin directory, accessing the following URL will allow you to see
what's going on in your UPS..

http://your.machine.dom/cgi-bin/upsstats.cgi

Making a bookmark to this script or linking to it from another page is an 
easy way to return to it in the future.

Using upsimage
==============

upsimage is also a CGI program like upsstats, but it is intended to be
called by IMG SRC requests inside the page that upsstats generates.
You can source the images from it directly if you like, but they may
look rather odd outside the table scheme of the normal upsstats page.
Most users will probably never need to touch upsimage directly.

Using upsc
==========

upsc, while intended as a small demonstration program of the upsfetch
library, can also be used to verify operation of the UPS where no
web browser is available or desired.  It takes two parameters - 
upsd host and ups parameter to query.  For example, to request the
model of the UPS connected to a machine called "elvis", you'd do..

$ upsc elvis model

The response you get depends on what's out there, but one such reply
might be "SMART-UPS 2200".

Parameters that may be queried...

     model - UPS model being monitored
   battcap - Battery capacity (0.0 - 100.0)
   utility - Current incoming utility power voltage 
   upsload - Percentage load on UPS (0.0 - 100.0)
    status - Bitmapped status field, returned in hex
   linemin - Minimum line voltage seen by UPS
   linemax - Maximum line voltage seen by UPS
   upstemp - Temperature inside UPS (degrees C)
outputfreq - Frequency of power coming out of ups (Hz)

Other issues
============

upsimage uses the gd library from http://www.boutell.com/ for quick 
generation of GIF images.  If you have something that needs speedy 
graphical representations of data that's being written in C, you should 
check it out.

