lagertonne/nut
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Wiki Activity

Imported Upstream version 2.6.2

Browse source
This commit is contained in:
Arnaud Quette 2011-09-29 20:14:46 +02:00
parent a367d9bc54
commit 45043b58d0
246 changed files with 18228 additions and 1415 deletions
Download patch file Download diff file Expand all files Collapse all files

314
docs/man/apcsmart.txt
View file

@ -11,30 +11,63 @@ SYNOPSIS
*apcsmart* -h
*apcsmart* -a 'UPS_NAME' ['OPTIONS']
*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
apcsmart driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
apcsmart should recognize all recent APC models that use a serial
protocol at 2400 bps. This is primarily the Smart-UPS, Matrix-UPS and
Back-UPS Pro lines.
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.
The driver attempts to support every bell and whistle of the APC
reporting interface, whether or not this is strictly sensible.
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):
Some older hardware may only report a handful of variables. This is
usually not a bug--they just don't support anything else.
[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=`
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-0024C cable is broken or missing, use this diagram to build
@ -42,42 +75,246 @@ a clone:
http://www.networkupstools.org/cables/940-0024C.jpg
EXTRA ARGUMENTS
---------------
You can specify alternate cable in linkman:ups.conf[5]:
This driver supports the following optional settings in the
linkman:ups.conf[5]:
*cable*=940-0095B
*cable=940-0095B*::
Configure the serial port for the APC 940-0095B dual-mode cable.
Alternatively, you can also provide it on the command line using:
*sdtype=*'num'::
Use shutdown type 'num', according to this table:
-x *cable*=940-0095B
0;; soft shutdown or powerdown, depending on battery status
EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES
------------------------------------------------------
1;; soft shutdown followed by powerdown
APC hardware supports a lot of shutdown methods, that themselves can differ in
behaviour quite a bit, depending on the model.
2;; instant power off
*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.*
3;; power off with grace period
"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.
4;; "force OB" hack method for CS 350
"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.
Modes 0 and 1 will power up the load when power returns. Modes 2 and 3
will keep the load turned off when the power returns.
*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).
Mode 4 exploits an oddity in the CS 350 models since they only seem to
support the S command, but then only when running on battery. As a
result, the driver will force the UPS to go on battery if necessary
before sending the shutdown command. This ensures that the load gets
reset.
*@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\'re 3 options used to control 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
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
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
@ -85,17 +322,20 @@ 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.
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
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
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 :