372 lines
13 KiB
Plaintext
372 lines
13 KiB
Plaintext
APCSMART(8)
|
|
===========
|
|
|
|
NAME
|
|
----
|
|
|
|
apcsmart - Driver for American Power Conversion Smart Protocol UPS equipment
|
|
|
|
SYNOPSIS
|
|
--------
|
|
|
|
*apcsmart* -h
|
|
|
|
*apcsmart* -a \'UPS_NAME' [-x option=value ...]
|
|
|
|
NOTE: This man page only documents the hardware-specific features of the
|
|
apcsmart driver. For information about the core driver, see
|
|
linkman:nutupsdrv[8].
|
|
|
|
|
|
SUPPORTED HARDWARE
|
|
------------------
|
|
|
|
The apcsmart driver should recognize (or at the very least work with) majority
|
|
of Smart-UPS models - which includes Smart-UPS, Matrix-UPS and Back-UPS lineups,
|
|
among few other ones.
|
|
|
|
Currently we can roughly divide APC hardware into 3 groups (note that the
|
|
division isn\'t strict by any means, and the borders between those are pretty fuzzy):
|
|
|
|
[very] "old" models::
|
|
These models usually have old APC logo, white color and _no_ programmable
|
|
eeprom; You won\'t find them listed anywhere on APC's site either. The support
|
|
for those will be usually based on driver\'s compatibility tables, or if the
|
|
model (firmware) is not listed in those - the driver will try to follow the very
|
|
basic subset of features, while still trying to remain useful. Despite
|
|
"smart" tagname, they often tend to behave in pretty dumb way (see the
|
|
section below about shutdown behaviour).
|
|
+
|
|
--
|
|
.Example models:
|
|
* Smart-UPS 2000I
|
|
* Smart-UPS 900I
|
|
--
|
|
|
|
"new" models::
|
|
These models usually come from late 1990s / pre-2009 times. They are often
|
|
referred as "3rd. gen". For the most part, they have programmable eeprom,
|
|
report supported commands and capabilites, and should work just fine with the
|
|
apcsmart driver.
|
|
|
|
"microlink" models::
|
|
WARNING: these are not _natively_ supported by apcsmart (or apcupsd for that
|
|
matter, if you\'re wondering). Around 2007 APC (now APC Schneider) decided to
|
|
go back to its proprietry roots and all the new models (SMT, SMX, SURTD) use
|
|
completely different protocol and cables. If you purchased a new APC UPS,
|
|
that uses cable with rj45 on the one end, and db-9 on the other - then you
|
|
have such model. Your only option to support it through *NUT* is to
|
|
purchase "legacy communications card" - part #AP9620 (google \'AP9620' for
|
|
more details). Or if that\'s not an option, rely on official software.
|
|
|
|
Another thing to remember is that Smart protocol is not USB protocol. If you
|
|
have UPS with both USB and serial ports, then depending on how you connect it,
|
|
you will need either apcsmart or usbhid-ups driver.
|
|
|
|
CABLING
|
|
-------
|
|
|
|
This driver expects to see a 940-0024C cable or a clone by default. You
|
|
can switch to the 940-0095B dual-mode cable support with the \'cable='
|
|
definition described below.
|
|
|
|
If your 940-xx24X cable is broken or missing, use this diagram to build
|
|
a clone:
|
|
|
|
http://www.networkupstools.org/cables.html#_940_0024c_clone
|
|
|
|
NOTE: The "xx" is either "00" for a short cable, or the number of feet
|
|
of a longer cable. The "X" is a letter representing the minor revision
|
|
of the physical cable and its connectors ("C" and "E" are commonly found
|
|
revisions). All minor revisions should use the same pin-outs and
|
|
wiring.
|
|
|
|
You can specify alternate cable in linkman:ups.conf[5]:
|
|
|
|
*cable*=940-0095B
|
|
|
|
Alternatively, you can also provide it on the command line using:
|
|
|
|
-x *cable*=940-0095B
|
|
|
|
TTY MODES
|
|
---------
|
|
|
|
By default the driver works in canonical mode, but it showed to be a problem in
|
|
windows systems. Furthermore there's a possibility of some obscure serial cards
|
|
or serial-usb convertes that could cause problems as well. You can use
|
|
\'ttymode=' option to force non-canonical discipline in linkman:ups.conf[5]:
|
|
|
|
*ttymode*=raw
|
|
|
|
Alternatively, you can also provide it on the command line using:
|
|
|
|
-x *ttymode*=raw
|
|
|
|
NOTE: Any other value will make the driver work in the canonical mode.
|
|
|
|
EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES
|
|
------------------------------------------------------
|
|
|
|
APC hardware supports a lot of shutdown methods, that themselves can differ in
|
|
behaviour quite a bit, depending on the model.
|
|
|
|
*S* (soft hibernate)::
|
|
This is most basic command present in probably all APC models. It will
|
|
hibernate the UPS, and subsequently wake it up when the mains supply
|
|
returns. *The command doesn\'t work if UPS is running on mains.*
|
|
|
|
"old" models:::
|
|
The behaviour here is unfortunately pretty primitive - when the power
|
|
returns, the UPS just wakes up. No grace periods, no min. battery
|
|
charge condition, etc. This is probably not what you want.
|
|
|
|
"new" models:::
|
|
The behaviour here is as expected - the power is cut off after the
|
|
eeprom defined grace period. The UPS will wake up when the power
|
|
returns, after the eeprom defined delay AND if the eeprom defined min.
|
|
battery charge level is met. The delay is counted from the power\'s
|
|
return.
|
|
|
|
*CS* (aka "force OB hack")::
|
|
This is a trick to make UPS power down even if it\'s running on mains.
|
|
Immediately before issuing *S*, "simulate power failure" is issued. The
|
|
remaining behaviour is as in *S* case.
|
|
+
|
|
The name came from APC CS models, where such trick was used to power down
|
|
UPSes in consistent fashion using only *S*. It\'s better to use *@nnn*
|
|
command if your UPS supports it (and is not too old, see below).
|
|
|
|
*@nnn* (hard hibernate)::
|
|
This is basic command used to hibernate UPS regardless if it\'s
|
|
running on batteries or on mains. The option takes 3 digits argument which
|
|
can be used to specify additional wakeup delay (in 6 minute units).
|
|
+
|
|
--
|
|
"old" models:::
|
|
The behaviour is - unfortunately - similary primitive to *S*. The UPS
|
|
unconditionally wakes up after $$nnn*6$$ minutes - *it doesn\'t care if the
|
|
power returned !* If nnn = 000, then UPS will do precisely nothing. On
|
|
those models you\'re better specifying nnn > 0, if you can estimate
|
|
the kind of power problems that might be happening in your environment.
|
|
Another thing to consider with "old" models - you might lose the
|
|
connection with the UPS, until it wakes up (with *S*, the serial
|
|
connection is kept alive).
|
|
|
|
"new" models:::
|
|
All the usual variables defined in eeprom are respected (see *S*).
|
|
Additionally, if nnn > 0, the $$nnn*6$$ minutes are added to eeprom
|
|
defined delay. UPS will not power up if it\'s running on batteries,
|
|
contrary to what "old" models used to do - the combined delay is counted
|
|
from the moment of power return.
|
|
--
|
|
+
|
|
Supposedly there exist models that take 2 digits instead of 3. Just in case,
|
|
NUT also supports such variation. You have to provide exactly 2 digits to
|
|
trigger it (*awd* option, or argument to one of the supported instant commands).
|
|
|
|
*K* (delayed poweroff)::
|
|
This is permanent poweroff - the UPS will not wake up automatically. On
|
|
newer units, it will respect applicable eeprom variables.
|
|
|
|
*Z* (instant poweroff)::
|
|
This is also permanent poweroff - the UPS will not wake up automatically.
|
|
The poweroff is executed immediately.
|
|
|
|
SHUTDOWN CONTROL BY NUT
|
|
-----------------------
|
|
|
|
There are three options used to control the shutdown behaviour.
|
|
|
|
*sdtype*=[0-5]::
|
|
This option takes a single digit (0-5) as an argument. See below for
|
|
details.
|
|
|
|
*advorder*=no|[0-4]+::
|
|
This option takes string of digits as an argument. Methods listed are tried
|
|
in turn until one of them succeedes. Note that the meaning of digits is
|
|
different from *sdtype*. See below for details.
|
|
|
|
*awd*=[0-9]{1,3}::
|
|
This option lets you specify additional wakeup delay used by *@*. If you
|
|
provide exactly 2 digits, the driver will try 2 digits variation (see
|
|
previous section for more info). Otherwise standard 3 digits variation is
|
|
used. *Note: the time unit is 6 minutes !*
|
|
|
|
Keep in mind that *sdtype* and *advorder* are mutually exclusive. If *advorder*
|
|
is provided, *sdtype* is ignored. If *advorder* is set to \'no', *sdtype* is
|
|
used instead.
|
|
|
|
If nothing is provided, *NUT* will assume *sdtype*=0 - which is generally fine
|
|
for anything not too ancient or not too quirky.
|
|
|
|
SDTYPE
|
|
~~~~~~
|
|
|
|
The values permitted are from 0 to 5. Only one can be specified. Anything else
|
|
will cause apcsmart to exit.
|
|
|
|
0::
|
|
issue soft hibernate (*S*) if the UPS is running on batteries, otherwise issue
|
|
hard hibernate (*@*)
|
|
1::
|
|
issue soft hibernate (*S*) (if on batteries), and if it fails (or on mains) -
|
|
try hard hibernate (*@*)
|
|
2::
|
|
issue instant poweroff (*Z*)
|
|
3::
|
|
issue delayed poweroff (*K*)
|
|
4::
|
|
issue "force OB hack" (*CS*)
|
|
5::
|
|
issue hard hibernate (*@*)
|
|
|
|
NOTE: Hard hibernate\'s additional wakeup delay can be provided by *awd*.
|
|
|
|
ADVORDER
|
|
~~~~~~~~
|
|
|
|
The argument is either a word \'no', or a string of 1 - 5 digits in [0 - 4]
|
|
range. Each digit maps to the one of shutdown methods supported by APC UPSes.
|
|
Methods listed in this way are tried in order, until one of them succedes.
|
|
|
|
If *advorder* is undefined or set to \'no', *sdtype* is used instead.
|
|
|
|
The mapping is as follows:
|
|
|
|
[horizontal]
|
|
0:: soft hibernate (*S*)
|
|
1:: hard hibernate (*@*)
|
|
2:: delayed poweroff (*K*)
|
|
3:: instant poweroff (*Z*)
|
|
4:: "force OB hack" (*CS*)
|
|
|
|
NOTE: Hard hibernate\'s additional wakeup delay can be provided by *awd*.
|
|
|
|
IGNORING LB STATE
|
|
-----------------
|
|
|
|
APC units - even if they report LB mode - will not go into shutdown
|
|
automatically. This gives us even more control with reference to "when to
|
|
actually shutdown psu". Since version 2.6.2, NUT supports *ignorelb* option in
|
|
driver\'s section of linkman:ups.conf[5]. When such option is in effect,
|
|
the core driver will ignore LB state as reported by specific driver and
|
|
start shutdown basing the decision _only_ on two conditions:
|
|
|
|
battery.charge < battery.charge.low
|
|
|
|
*OR*
|
|
|
|
battery.runtime < battery.runtime.low
|
|
|
|
Of course - if any of the variables are not available, the appropriate condition
|
|
is not checked. If you want to explicitly disable one of the conditions, simply
|
|
override the right hand variable causing the condition to always evaluate to
|
|
false (you can even provide negative numbers).
|
|
|
|
APC UPSes don\'t have battery.charge.low - you will have to define it if you want
|
|
to use such condition (prefix the variable with override. or default.).
|
|
|
|
"New" units have battery.runtime.low, but depending on battery quality, firmware
|
|
version, calibration and UPS load - this variable can be underestimated quite a bit -
|
|
especially right after going into OB state. This in turn can cause LB to be
|
|
asserted, which under normal conditions will cause *NUT* to initiate the
|
|
shutdown. You might want to disable this condition entirely, when relying on
|
|
*ignorelb* option (this was actually the main motivation behind introduction of
|
|
such feature).
|
|
|
|
Simple example:
|
|
|
|
[source,conf]
|
|
----
|
|
[apc]
|
|
ignorelb
|
|
override.battery.charge.low = 15
|
|
override.battery.runtime.low = -1
|
|
----
|
|
|
|
This would cause apcsmart to go into shutdown _only_ if detected battery charge
|
|
< 15%. Runtime condition is always false in this example.
|
|
|
|
You could ask - why bother ? Well, the reason is already hinted above. APC units
|
|
can be very picky about the batteries, and their firmware can underestimate the
|
|
remaining runtime (especially right after going into OB state). *ignorelb*
|
|
option and *$$override.*$$* let you remain in control of the UPS, not UPS in control
|
|
of you.
|
|
|
|
Furthermore, this allows to specify conditions similary to how it's done in
|
|
apcupsd daemon, so it should be welcome by people used to that software.
|
|
|
|
|
|
SUPPORTED INSTANT COMMANDS
|
|
--------------------------
|
|
|
|
The apcsmart driver exposes following instant commands:
|
|
|
|
shutdown.return::
|
|
executes soft hibernate
|
|
shutdown.return cs::
|
|
executes "force OB hack"
|
|
shutdown.return at:<nbr>::
|
|
executes "hard hibernate" with $$<nbr>*6$$ minutes additional wakeup delay (<nbr> format
|
|
is the same as of *awd* option)
|
|
shutdown.stayoff::
|
|
executes "delayed poweroff"
|
|
load.off::
|
|
executes "instant poweroff"
|
|
|
|
All the above commands must be issued 2nd time to have any effect (no less than 3
|
|
seconds, and no more than 15 seconds after the initial call). Those commands are
|
|
mostly useful for manual testing, when your machine is not powered by the UPS
|
|
you\'re testing.
|
|
|
|
Other supported commands:
|
|
|
|
- load.on
|
|
- test.panel.start
|
|
- test.failure.start
|
|
- test.battery.start
|
|
- test.battery.stop
|
|
- bypass.start
|
|
- bypass.stop
|
|
- calibrate.start
|
|
- calibrate.stop
|
|
|
|
PREVIOUS DRIVER VERSION
|
|
-----------------------
|
|
|
|
Previous driver is still available as apcsmart-old - should there be any need to
|
|
use earlier version (bugs, incompatiblities with new functionality, etc.). In
|
|
due time apcsmart-old will be phased out completely, but this won't happen until
|
|
the new version gets solid exposure with no pending issues.
|
|
|
|
BUGS
|
|
----
|
|
|
|
Some older APC UPS models return bogus data in the status register during
|
|
a front panel test. This is usually detected and discarded, but some
|
|
other unexpected values have occasionally slipped through.
|
|
|
|
APC UPS models with both USB and serial ports require a power cycle when
|
|
switching from USB communication to serial, and perhaps vice versa.
|
|
|
|
AUTHOR
|
|
------
|
|
|
|
Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
|
|
heavily on the original apcsmart driver by Russell Kroll). This driver
|
|
was called newapc for a time and was renamed in the 1.5 series. In 2.6.2
|
|
it was renamed to apcsmart-old, being superseded by updated version with
|
|
new features, which is maintained by Michal Soltys <soltys@ziu.info>
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
linkman:nutupsdrv[8], linkman:ups.conf[5]
|
|
|
|
Internet resources:
|
|
~~~~~~~~~~~~~~~~~~~
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|
|
|
|
// vim: tw=80 ai si ts=8 sts=4 sw=4 et :
|