docs/contact-closure.txt

   1 Contact closure hardware information
   2 ------------------------------------
   3
   4 This is a collection of notes that apply to contact closure UPS
   5 hardware, specifically those monitored by the genericups driver.
   6
   7 Definitions
   8 ~~~~~~~~~~~
   9
  10 "Contact closure" refers to a situation where one line is connected to
  11 another inside UPS hardware to indicate some sort of situation.  These
  12 can be relays, or some other form of switching electronics.  The generic
  13 idea is that you either have a signal on a line, or you don't.  Think
  14 binary.
  15
  16 Usually, the source for a signal is the host PC.  It provides a high
  17 (logic level 1) from one of its outgoing lines, and the UPS returns it
  18 on one or more lines to communicate.  The rest of the time, the UPS
  19 either lets it float or connects it to the ground to indicate a 0.
  20
  21 Other equipment generates the high and low signals internally, and does
  22 not require cable power.  These signals just appear on the right lines
  23 without any special configuration on the PC side.
  24
  25 Bad levels
  26 ~~~~~~~~~~
  27
  28 Some evil cabling and UPS equipment uses the transmit or receive lines
  29 as their reference points for these signals.  This is not sufficient to
  30 register as a high signal on many serial ports.  If you have problems
  31 reading certain signals on your system, make sure your UPS isn't trying
  32 to do this.
  33
  34 Signals
  35 ~~~~~~~
  36
  37 Unlike their smarter cousins, this kind of UPS can only give you very
  38 simple yes/no answers.  Due to the limited number of serial port lines
  39 that can be used for this purpose, you typically get two pieces of data:
  40
  41         1. "On line" or "on battery"
  42         2. "Battery OK" or "Low battery"
  43
  44 That's it.  Some equipment actually swaps the second one for a
  45 notification about whether the battery needs to be replaced, which makes
  46 life interesting for those users.
  47
  48 Most hardware also supports an outgoing signal from the PC which means
  49 "shut down the load immediately".  This is generally implemented in such
  50 a way that it only works when running on battery.  Most hardware or
  51 cabling will ignore the shutdown signal when running on line power.
  52
  53 New genericups types
  54 ~~~~~~~~~~~~~~~~~~~~
  55
  56 If none of the existing types in the genericups driver work completely,
  57 make a note of which ones (if any) manage to work partially.  This can
  58 save you some work when creating support for your hardware.
  59
  60 Use that information to create a list of where the signals from your UPS
  61 appear on the serial port at the PC end, and whether they are active
  62 high or active low.  You also need to know what outgoing lines, if any,
  63 need to be raised in order to supply power to the contacts.  This is
  64 known as cable power.  Finally, if your UPS can shut down the load, that
  65 line must also be identified.
  66
  67 There are only 4 incoming and 2 outgoing lines, so not many combinations
  68 are left.  The other lines on a typical 9 pin port are transmit,
  69 receive, and the ground.  Anything trying to do a high/low signal on
  70 those three is beyond the scope of the genericups driver.  The only
  71 exception is an outgoing BREAK, which we already support.
  72
  73 When editing the genericups.h, the values have the following meanings:
  74
  75 Outgoing lines:
  76
  77 - line_norm = what to set to make the line "normal" - i.e. cable power
  78 - line_sd   = what to set to make the UPS shut down the load
  79
  80 Incoming lines:
  81
  82 - line_ol   = flag that appears for on line / on battery
  83 - val_ol    = value of that flag when the UPS is on battery
  84 - line_bl   = flag that appears for low battery / battery OK
  85 - val_bl    = value of that flag when the battery is low
  86
  87 This may seem a bit confusing to have two variables per value that
  88 we want to read, but here's how it works.  If you set line_ol to
  89 TIOCM_RNG, then the value of TIOCM_RNG (0x080 on my box) will be anded
  90 with the value of the serial port whenever a poll occurs.  If that flag
  91 exists, then the result of the and will be 0x80.  If it does not exist,
  92 the result will be 0.
  93
  94 So, if line_ol = foo, then val_ol can only be foo or 0.
  95
  96 As a general case, if 'line_ol == val_ol', then the value you're reading
  97 is active high.  Otherwise, it's active low.  Check out the guts of
  98 upsdrv_updateinfo() to see how it really works.
  99
 100 Custom definitions
 101 ~~~~~~~~~~~~~~~~~~
 102
 103 Late in the 1.3 cycle, a feature was merged which allows you to create
 104 custom monitoring settings without editing the model table.  Just set
 105 upstype to something close, then use settings in ups.conf to adjust the
 106 rest.  See the linkman:genericups[8] man page for more
 107 details.