APC Smart-UPS info

The following information was provided by der Mouse <mouse@Rodents.Montreal.QC.CA>
and appears here with his permission.

The info about the S shutdown is of special interest to me...
if I can verify its behaviour during an extended shutdown I'll modify my apcmon script to use it.

--sjg

Date: Wed, 2 Apr 1997 15:39:17 -0500 (EST)
From: der Mouse  
Message-Id: <199704022039.PAA26760@Twig.Rodents.Montreal.QC.CA>
To: sjg@crufty.net
Cc: mouse@Twig.Rodents.Montreal.QC.CA
Subject: Re: UPS unattended shutdown

> See http://www.crufty.net/sjg/apcmon.html

I arranged access to a Smart-UPS 2200XL and I find that:

- You don't need APC's cable.  The book that comes with the UPS
   documents two of the lines as having RS-232 signal levels; it turns
   out that a cable that hooks them to pins 2 and 3, and ground to
   ground, works Just Fine for me.  (DB9M pin 1 to DB25M pin 2; DB9M
   pin 2 to DB25M pin 3; DB9M pin 4 to DB25M pin 7.)  The 2200XL is
   supposed to be a "smart signaling" UPS, so I assume the black cable
   (plus an appropriate DB9-DB25 converter) would have this or a
   similar pinout.

- The interface, at least for the 2200XL, is a lot more complicated
   than the one your scripts imply.  I don't know it all yet, but I
   know enough to be useful. :-)

- Yes, I read the note in the front of the PowerChute book (another lab
   whose sysadmin I'm on good terms with uses the real thing); however,
   I carefully didn't use their package, so I didn't thereby agree not
   to reverse-engineer anything.

I'm sending this to you 'cause you're the best (indeed, only)
repository of UPS info I know of. :-)

Communication is at 2400 baud.

The UPS is in one of three states at any time:

- Dead state: no lights, no response at all to serial line.
- Dumb state: RS232 receive line is shutdown signal (high for 4.5
    seconds initiates shutdown); RS232 send line is powerfail signal.
    Additionally, the RS232 line is monitored for a 0x59 (Y) character,
    which is the signal to switch into smart mode.  As far as I can
    tell nothing but Y or the 4.5-second signal gets the UPS's
    attention in dumb mode.
- Smart state: RS232 send and receive lines are normal RS232.  I don't
    know whether a 4.5 second break condition will initiate a shutdown.

Transitions as following are possible; as far as I know no others are
possible:

Dead->dumb: front-panel-initiated power-up, or in some cases mains
power returning

Dumb->smart: receiving the Y command

Dumb->dead: front-panel-initiated power-down, also apparently some
timeout (completely drained batteries?) when in
4.5-second-break-initiated shutdown mode.

Smart->dumb: receiving the R command; also, front-panel-initiated
power-up from a software-initiated shutdown state seems to do this.

Smart->dead: Some timeout when in a shutdown state, even if batteries
aren't completely drained.

The rest of this document describes only smart mode.

Normally, the UPS is silent except for replies to commands.  However,
there are a few characters it will gratuitously send.  Here are my best
guesses at them:

!	Sent periodically (approx. every 30 seconds) while running on
	battery.

$	Sent, once, when returning from on-battery to mains power.

?	Sent, once, on front-panel-initiated power-up (and enters dumb
	mode).

|	I've seen it but I don't know what it means.  It may have
	something to do with worn-out batteries.

%, +	Unsure.  Low battery seems to send alternating % and + every
	few seconds while beeping like mad.  I have seen % and + in
	other contexts though.

In the following list of commands, "adjustable" means the + and -
commands do something useful, usually cycling through a small number of
values; "prog-adjust" means "adjustable, but only in PROG mode" (see
the 1 command).  Prog-adjust values usually adjust a two-nibble hex
value.

The first column is the character, either the character itself for
space-through-tilde or a two-digit hex code prefixed with 0x for
characters outside that range.  I have tried all 256 single-byte
commands; all byte values not listed here consistently reply NA.
"reply" means that the indicated string is sent, followed by a CR/LF
pair.  Except for values noted as adjustable, prog-adjust, or whose
description explicitly mentions otherwise, the + and - commands return
NO.)  When multiple "reply" lines are given, this means I have seen
each of those strings under at least some circumstances.  Some commands
have [...] comments after the ->; these indicate semantics that some
source has attributed to that value and I have seen no reason to
disbelieve.  "S shutdown" refers to the power-down state after a
shutdown initiated by the S command.  In this state, six of the
front-panel lights do a cute marquee-like pattern.

0x01 -> reply SMART-UPS 2200 XL
	(Presumably this is some sort of self-identify command.)
0x0e -> no reply
0x1a -> reply #uD43132135138129uM43229234239224uA43110112114108uI43253264271280lD43103100097106lM43177172168182lA43090092081085lI43196188208204e44200155090oI43230240220225oD13115oJ13100oM13208s441HMLLq44202050710p443020180300600k4410TLNr443000060180300E443336168ON OFF
	(I have no clue what this string means.)
' -> reply 00
+ -> if last value is adjustable, adjust upwards and reply with
	two-nibble hex (PROG mode) or OK (non-PROG mode).  Otherwise,
	reply NO.  (In non-PROG mode, only one + or - is allowed before
	re-issuing the display command.)
- -> if last value is adjustable, adjust downwards and reply with
	two-nibble hex (PROG mode) or OK (non-PROG mode).  Otherwise,
	reply NO.  (In non-PROG mode, only one + or - is allowed before
	re-issuing the display command.)
0 -> reply 9F (prog-adjust)
1 -> no reply; it eats anywhere from zero upwards of the following
	characters.  In some cases (I have no reliable way of provoking
	this, but usually can manage it within a few tries) it will
	reply PROG, which indicates that the UPS has entered PROG mode.
	In PROG mode, + and - can adjust prog-adjust values and can be
	given multiple times in succession.
4 -> reply 28 (prog-adjust)
5 -> reply F1 (prog-adjust)
6 -> reply F9 (prog-adjust)
7 -> reply 00
8 -> reply 00
     reply 10 (after S shutdown)
9 -> reply FF
     reply 00
> -> [battery count] reply 000 (8-bit unsigned, in decimal(!), adjustable)
? -> reply 33AB
     reply 33AC
     reply 0000
     reply 33AD
@ -> no reply, eats next character (?)
     reply NA (after S shutdown)
A -> [test LEDs] burn all LEDs, beep, send OK immediately
B -> [battery voltage, volts] reply 55.65
     reply 51.85
     reply 50.25
     (prog-adjust)
C -> [battery temp, deg C] reply 029.2
     reply 023.4
D -> reply NO
     reply NA (after S shutdown)
E -> reply 336
F -> [freq, hz] reply 60.0
     reply 60.00
G -> reply S
K -> no reply, but if repeated "soon" (for some suitable value of
	"soon"), replies OK and powers down hard (not to S-shutdown
	mode) after p time.
L -> [some voltage?] reply 114.4
     reply 000.0
     (prog-adjust)
M -> [some voltage?] reply 115.7
     reply 000.0
N -> [some voltage?] reply 113.7
     reply 000.0
O -> [some voltage?] reply 114.4
     reply 119.6
     reply 000.0 (after S shutdown)
P -> [load, %] reply 003.6
     reply 005.2
     (prog-adjust)
Q -> [status, first digit on-battery-p] reply 08
     reply 10
     reply 00 (after S shutdown)
R -> reply BYE and enter dumb state
S -> reply NA (when running on mains power)
     reply OK, pause, shut down and enter S shutdown mode
     reply NA (after S shutdown)
U -> [simulate powerfail] reply OK, do power-fail (and power-restore) sequence
     reply NA (after S shutdown)
V -> reply MWD
W -> [do self-test] reply OK, initiate self-test
     reply NA (after S shutdown)
X -> [self-test status?] reply OK
     reply NG (after S shutdown)
     reply NO (??)
Y -> reply SM (this is the only command that works when in dumb mode)
     if in dumb mode and on battery, the break condition makes the reply
     look different - I see 0x00 0xea 0x4d instead of 0x53 0x4d - but
     smart mode is entered and a second Y will reply with a clear SM.
Z -> no reply
     reply NA (after S shutdown)
a -> reply 3.!$%+?=#|.^A^N^Z+-789>@ABCDEFGKLMNOPQRSUVWXYZ'abcefgjklmnopqrsuxyz~^?
	(Note: the ^A, ^N, ^Z, and ^? digraphs above correspond to
	0x01, 0x0e, 0x1a, and 0x7f bytes in the actual response.)  I
	don't know what, if anything, the 3.!$%+?=#|. part means, but
	the rest of it appears to be a list of commands that do
	something.  The only commands that I know do anything that are
	not listed there are 0 1 4 5 6 ? (qv); there are no commands
	listed there that I do not list here.
b -> reply 81.9.D
     (prog-adjust)
	(I don't have a clue what this is.)
c -> reply UPS_IDEN
     (+ or - makes it eat next 8 bytes and store them here)
e -> [wakeup capacity, %] reply 00
     (adjustable with + and -, cycles through 00, 15, 50, 90)
f -> [battery capacity, %] reply 089.0
     reply 086.0
g -> reply 048
	(I have no clue what this value is.)
j -> reply 0307:
     reply 0220:
     reply 0185:
     reply 0176:
     reply 0129:
     reply 0118:
     reply 0123:
     reply 0126:
     reply 0116:
     reply 0087:
     reply 0088:
     reply 0105:
     reply 0110:
     is this remaining on-battery run time at current load, perhaps?
k -> [audible alarm] reply 0
     (adjustable with + and -, cycles through 0 T L N)
l -> [low transfer point] reply 103
     (adjustable with + and -, cycles through 103 100 097 106)
m -> reply 10/07/96
     (PROG-mode + or - makes it eat next 8 bytes and store them here)
n -> reply ES9633162488^@^@
     (note the ^@ digraphs correspond to 0x00 bytes in the response.)
     (PROG-mode + or - makes it eat next 14 bytes and store them here)
o -> [output volatge on battery] reply 115
p -> [shutdown time, sec] reply 020
     (adjustable with + and -, cycles through 020 180 300 600)
q -> [low-battery warning time, minutes] reply 02
     (adjustable with + and -, cycles through 02 05 07 10)
r -> [wakeup delay, sec] reply 000
     (adjustable with + and -, cycles through 000 060 180 300)
s -> [line sensitivity, H/M/L] reply H
     (adjustable with + and -, cycles through H M L L)
u -> [high transfer point] reply 132
     (adjustable with + and -, cycles through 132 135 138 129)
x -> reply 10/07/96
     (+ or - makes it eat next 8 bytes and store them here)
y -> reply (C) APCC
z -> reply CLEAR, reset to defaults; in PROG mode, resets more values.
~ -> reply 00
	(I don't know what this is.)
0x7f -> reply NO
        reply OK and power up (after S shutdown)

					der Mouse

			       mouse@rodents.montreal.qc.ca
		     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B