Desc: Information about the MGE-UTALK drivers
File: mge-utalk.txt
Date: 10 May 2002
Auth: Hans Ekkehard Plesser <hans.plesser@itf.nlh.no>


Models
======
This driver has been tested with:
    
  Pulsar ESV 22+
  Pulsar EX 10
  Pulsar EX 15
  Pulsar EXtreme 1500
  Evolution 800
  ES 8+


Operating Systems
=================
This driver has been tested under:

  Linux (SuSE 7.2, RedHat 7.2, Debian)
  Solaris 2.6


Compilers
=========

  gcc egcs-2.91.66
  gcc 2.95.4
  gcc 3.0.3
  Sun Workshop 5


Comments
========

Not all MGE UPS models provide all possible information.  The driver
checks on startup which variables are available from the UPS, and
re-reads these regularly.  It will issue warnings like

	 initinfo: XXX unavailable

for any quantity your UPS does not provide (e.g., the ESV 22+ does not
provide temperature readings).  This is nothing to worry about.  

In the same way, not all commands are supported by all machines, e.g.,
the ESV 22+ runs no FPTEST.

Startup is a bit slow, but this should not matter much.

The shutdown command has to be invoked twice within 3-12 sec to apply
it.  INFO_STATUS shows FSD after a shutdown has been initiated.  The
system will power up again when power returns.  Note that the shutdown
delay (sddelay, -d) is set in seconds, while the power on delay (-x
OnDelay=...) is set in minutes.  

The UPS raises the LB flag (low battery) if the load level drops below
LowBatt percent (-x LowBatt=...).


Files
=====

models/mge-utalk.h
models/mge-utalk.c
docs/drivers/mge-utalk.txt


Implementation Details
======================

mge-utalk.h defines a struct array that tells the driver how to read
variables from the UPS and publish them as INFO_ data.  Feel free to
add any further variables/commands to this structure!  Just be careful
not to delete the NULL-element at the end of the list.

Default variable settings (LowBatt, OnDelay, OffDelay) are also
defined in mge-utalk.h, while internal constants are defined in
mge-utalk.c.  The logic behind this is that anything internal should
be hidden in the *.c file.

The INFO_STATUS variable is not included in this array, since it
contains information that requires several calls to the UPS and more
advanced analysis of the reponses.  function get_ups_status does this
job.  Note that MGE enumerates the status "bits" from right to left,
i.e., if buf[] contains the reponse to command "Ss" (read system
status), then buf[0] contains "bit" Ss.1.7 (General alarm), while
buf[7] contains "bit" Ss.1.0 (Load unprotected). 

enable_ups_comm() is called before each attempt to read/write data
from the UPS to make sure that the machine is using the proper
protocol settings.

Running with -DDDD, all bytes sent to the UPS will be shown.


References
==========

MGE has published detailed technical information, in particular 

    - Specification of ASCII Protocol for UPS Product
    - Specification of ASCII Protocol, UPS Data Matrix

Both are available at http://www.mgeups.com/techinfo/techdoc
or at http://www.exploits.org/nut/library/protocols/mge/
    


Changes
=======

0.51.0
------
- Handle TRUE/FALSE previous definition
- Cosmethic modifications on the banner and MODEL
- Added instand commands CMD_OFF, CMD_ON (both are still beta)
  and CMD_BYPASS (not yet tested)
- Changed unavailable features output from log to debug
- Added RW_FLAG to some variable to allow setting those:
  * LOWXFER, LOBOOSTXFER, HIBOOSTXFER, LOTRIMXFER, 
    HITRIMXFER, HIGHXFER: min/max/default/unit(depending on unit),
    CAUTION => to set 240 V, enter 24000; 18500 for 185 V, ...
  * WAKEDELAY (OnDelay): min(0), max(65535), default(0), unit(min)
  * GRACEDELAY (OffDelay): min(0), max(65535), default(120), unit(sec)
  * SLFTSTINT: min(0 or 1440), max(65535), default(10080), unit(min)
  * LOBATTPCT (LowBatt): : min/max(depending on unit), default(30), unit(%)

0.50.0a
-------
- Send "Z" twice in enable_ups_comm
- sddelay/option -d now inactive; use -x OffDelay= to set shut-down
  delay of UPS
- Totally redone communication.  Functionality of both upssend and
  upsrecv is now handle by mge_command(). 
- Missing multiplier table gives warning now, driver runs with table 0.
- strtok eliminated.

0.50.0b
-------
- status_init() now properly in get_ups_status
- decreased MGE_REPLY_DELAY, introduced MGE_CONNECT_DELAY 
  in enable_ups_comm()

To Do
=====

* Option -d (setting sddelay) is ignored now.  The driver should wait
  this long before it itself shuts down.  As Russell writes: 

    sddelay is supposed to be how long the _driver_ waits for the
    shutdown, not necessarily the UPS.  It's there so you can make the
    driver stick around for awhile until the computer gets turned off.
    If it exits, you should reboot, since something failed.

* Commands should report back to upscmd, once the back-channel is
  implemented in upsd.

* Sort out "OFF OL" issues: OFF is set according to Ls.2.7, but maybe
  this interpretation is in conflict with the NUT interpretation of
  the OFF flag?

* Add selectable plug number for ON/OFF commands
