525 lines
16 KiB
Groff
525 lines
16 KiB
Groff
'\" t
|
|
.\" Title: apcsmart
|
|
.\" Author: [see the "AUTHOR" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
|
.\" Date: 08/07/2012
|
|
.\" Manual: NUT Manual
|
|
.\" Source: Network UPS Tools
|
|
.\" Language: English
|
|
.\"
|
|
.TH "APCSMART" "8" "08/07/2012" "Network UPS Tools" "NUT Manual"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
apcsmart \- Driver for American Power Conversion Smart Protocol UPS equipment
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
\fBapcsmart\fR \-h
|
|
.sp
|
|
\fBapcsmart\fR \-a \*(AqUPS_NAME\*(Aq [\-x option=value \&...]
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
This man page only documents the hardware\-specific features of the apcsmart driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
|
|
.sp .5v
|
|
.RE
|
|
.SH "SUPPORTED HARDWARE"
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
Currently we can roughly divide APC hardware into 3 groups (note that the division isn\*(Aqt strict by any means, and the borders between those are pretty fuzzy):
|
|
.PP
|
|
[very] "old" models
|
|
.RS 4
|
|
These models usually have old APC logo, white color and
|
|
\fIno\fR
|
|
programmable eeprom; You won\*(Aqt find them listed anywhere on APC\(cqs site either\&. The support for those will be usually based on driver\*(Aqs 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)\&.
|
|
.PP
|
|
\fBExample models:\fR
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
Smart\-UPS 2000I
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
Smart\-UPS 900I
|
|
.RE
|
|
.RE
|
|
.PP
|
|
"new" models
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
"microlink" models
|
|
.RS 4
|
|
WARNING: these are not
|
|
\fInatively\fR
|
|
supported by apcsmart (or apcupsd for that matter, if you\(cqre 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
|
|
\fBNUT\fR
|
|
is to purchase "legacy communications card" \- part #AP9620 (google \*(AqAP9620\*(Aq for more details)\&. Or if that\*(Aqs not an option, rely on official software\&.
|
|
.RE
|
|
.sp
|
|
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\&.
|
|
.SH "CABLING"
|
|
.sp
|
|
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 \*(Aqcable=\*(Aq definition described below\&.
|
|
.sp
|
|
If your 940\-xx24X cable is broken or missing, use this diagram to build a clone:
|
|
.sp
|
|
http://www\&.networkupstools\&.org/cables\&.html#_940_0024c_clone
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
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\&.
|
|
.sp .5v
|
|
.RE
|
|
.sp
|
|
You can specify alternate cable in \fBups.conf\fR(5):
|
|
.sp
|
|
\fBcable\fR=940\-0095B
|
|
.sp
|
|
Alternatively, you can also provide it on the command line using:
|
|
.sp
|
|
\-x \fBcable\fR=940\-0095B
|
|
.SH "EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES"
|
|
.sp
|
|
APC hardware supports a lot of shutdown methods, that themselves can differ in behaviour quite a bit, depending on the model\&.
|
|
.PP
|
|
\fBS\fR (soft hibernate)
|
|
.RS 4
|
|
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\&.
|
|
\fBThe command doesn\*(Aqt work if UPS is running on mains\&.\fR
|
|
.PP
|
|
"old" models
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
"new" models
|
|
.RS 4
|
|
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\*(Aqs return\&.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\fBCS\fR (aka "force OB hack")
|
|
.RS 4
|
|
This is a trick to make UPS power down even if it\*(Aqs running on mains\&. Immediately before issuing
|
|
\fBS\fR, "simulate power failure" is issued\&. The remaining behaviour is as in
|
|
\fBS\fR
|
|
case\&.
|
|
.sp
|
|
The name came from APC CS models, where such trick was used to power down UPSes in consistent fashion using only
|
|
\fBS\fR\&. It\*(Aqs better to use
|
|
\fB@nnn\fR
|
|
command if your UPS supports it (and is not too old, see below)\&.
|
|
.RE
|
|
.PP
|
|
\fB@nnn\fR (hard hibernate)
|
|
.RS 4
|
|
This is basic command used to hibernate UPS regardless if it\*(Aqs 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)\&.
|
|
.PP
|
|
"old" models
|
|
.RS 4
|
|
The behaviour is \- unfortunately \- similary primitive to
|
|
\fBS\fR\&. The UPS unconditionally wakes up after nnn*6 minutes \-
|
|
\fBit doesn\*(Aqt care if the power returned !\fR
|
|
If nnn = 000, then UPS will do precisely nothing\&. On those models you\*(Aqre 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
|
|
\fBS\fR, the serial connection is kept alive)\&.
|
|
.RE
|
|
.PP
|
|
"new" models
|
|
.RS 4
|
|
All the usual variables defined in eeprom are respected (see
|
|
\fBS\fR)\&. Additionally, if nnn > 0, the nnn*6 minutes are added to eeprom defined delay\&. UPS will not power up if it\*(Aqs running on batteries, contrary to what "old" models used to do \- the combined delay is counted from the moment of power return\&.
|
|
.RE
|
|
.sp
|
|
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 (\fBawd\fR
|
|
option, or argument to one of the supported instant commands)\&.
|
|
.RE
|
|
.PP
|
|
\fBK\fR (delayed poweroff)
|
|
.RS 4
|
|
This is permanent poweroff \- the UPS will not wake up automatically\&. On newer units, it will respect applicable eeprom variables\&.
|
|
.RE
|
|
.PP
|
|
\fBZ\fR (instant poweroff)
|
|
.RS 4
|
|
This is also permanent poweroff \- the UPS will not wake up automatically\&. The poweroff is executed immediately\&.
|
|
.RE
|
|
.SH "SHUTDOWN CONTROL BY NUT"
|
|
.sp
|
|
There are three options used to control the shutdown behaviour\&.
|
|
.PP
|
|
\fBsdtype\fR=[0\-5]
|
|
.RS 4
|
|
This option takes a single digit (0\-5) as an argument\&. See below for details\&.
|
|
.RE
|
|
.PP
|
|
\fBadvorder\fR=no|[0\-4]+
|
|
.RS 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
|
|
\fBsdtype\fR\&. See below for details\&.
|
|
.RE
|
|
.PP
|
|
\fBawd\fR=[0\-9]{1,3}
|
|
.RS 4
|
|
This option lets you specify additional wakeup delay used by
|
|
\fB@\fR\&. 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\&.
|
|
\fBNote: the time unit is 6 minutes !\fR
|
|
.RE
|
|
.sp
|
|
Keep in mind that \fBsdtype\fR and \fBadvorder\fR are mutually exclusive\&. If \fBadvorder\fR is provided, \fBsdtype\fR is ignored\&. If \fBadvorder\fR is set to \*(Aqno\*(Aq, \fBsdtype\fR is used instead\&.
|
|
.sp
|
|
If nothing is provided, \fBNUT\fR will assume \fBsdtype\fR=0 \- which is generally fine for anything not too ancient or not too quirky\&.
|
|
.SS "SDTYPE"
|
|
.sp
|
|
The values permitted are from 0 to 5\&. Only one can be specified\&. Anything else will cause apcsmart to exit\&.
|
|
.PP
|
|
0
|
|
.RS 4
|
|
issue soft hibernate (\fBS\fR) if the UPS is running on batteries, otherwise issue hard hibernate (\fB@\fR)
|
|
.RE
|
|
.PP
|
|
1
|
|
.RS 4
|
|
issue soft hibernate (\fBS\fR) (if on batteries), and if it fails (or on mains) \- try hard hibernate (\fB@\fR)
|
|
.RE
|
|
.PP
|
|
2
|
|
.RS 4
|
|
issue instant poweroff (\fBZ\fR)
|
|
.RE
|
|
.PP
|
|
3
|
|
.RS 4
|
|
issue delayed poweroff (\fBK\fR)
|
|
.RE
|
|
.PP
|
|
4
|
|
.RS 4
|
|
issue "force OB hack" (\fBCS\fR)
|
|
.RE
|
|
.PP
|
|
5
|
|
.RS 4
|
|
issue hard hibernate (\fB@\fR)
|
|
.RE
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Hard hibernate\*(Aqs additional wakeup delay can be provided by \fBawd\fR\&.
|
|
.sp .5v
|
|
.RE
|
|
.SS "ADVORDER"
|
|
.sp
|
|
The argument is either a word \*(Aqno\*(Aq, 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\&.
|
|
.sp
|
|
If \fBadvorder\fR is undefined or set to \*(Aqno\*(Aq, \fBsdtype\fR is used instead\&.
|
|
.sp
|
|
The mapping is as follows:
|
|
.TS
|
|
tab(:);
|
|
lt lt
|
|
lt lt
|
|
lt lt
|
|
lt lt
|
|
lt lt.
|
|
T{
|
|
.sp
|
|
0
|
|
T}:T{
|
|
.sp
|
|
soft hibernate (\fBS\fR)
|
|
T}
|
|
T{
|
|
.sp
|
|
1
|
|
T}:T{
|
|
.sp
|
|
hard hibernate (\fB@\fR)
|
|
T}
|
|
T{
|
|
.sp
|
|
2
|
|
T}:T{
|
|
.sp
|
|
delayed poweroff (\fBK\fR)
|
|
T}
|
|
T{
|
|
.sp
|
|
3
|
|
T}:T{
|
|
.sp
|
|
instant poweroff (\fBZ\fR)
|
|
T}
|
|
T{
|
|
.sp
|
|
4
|
|
T}:T{
|
|
.sp
|
|
"force OB hack" (\fBCS\fR)
|
|
T}
|
|
.TE
|
|
.sp 1
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
Hard hibernate\*(Aqs additional wakeup delay can be provided by \fBawd\fR\&.
|
|
.sp .5v
|
|
.RE
|
|
.SH "IGNORING LB STATE"
|
|
.sp
|
|
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 \fBignorelb\fR option in driver\*(Aqs section of \fBups.conf\fR(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 \fIonly\fR on two conditions:
|
|
.sp
|
|
battery\&.charge < battery\&.charge\&.low
|
|
.sp
|
|
\fBOR\fR
|
|
.sp
|
|
battery\&.runtime < battery\&.runtime\&.low
|
|
.sp
|
|
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)\&.
|
|
.sp
|
|
APC UPSes don\*(Aqt have battery\&.charge\&.low \- you will have to define it if you want to use such condition (prefix the variable with override\&. or default\&.)\&.
|
|
.sp
|
|
"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 \fBNUT\fR to initiate the shutdown\&. You might want to disable this condition entirely, when relying on \fBignorelb\fR option (this was actually the main motivation behind introduction of such feature)\&.
|
|
.sp
|
|
Simple example:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[apc]
|
|
ignorelb
|
|
override\&.battery\&.charge\&.low = 15
|
|
override\&.battery\&.runtime\&.low = \-1
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
This would cause apcsmart to go into shutdown \fIonly\fR if detected battery charge < 15%\&. Runtime condition is always false in this example\&.
|
|
.sp
|
|
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)\&. \fBignorelb\fR option and \fBoverride\&.*\fR let you remain in control of the UPS, not UPS in control of you\&.
|
|
.sp
|
|
Furthermore, this allows to specify conditions similary to how it\(cqs done in apcupsd daemon, so it should be welcome by people used to that software\&.
|
|
.SH "SUPPORTED INSTANT COMMANDS"
|
|
.sp
|
|
The apcsmart driver exposes following instant commands:
|
|
.PP
|
|
shutdown\&.return
|
|
.RS 4
|
|
executes soft hibernate
|
|
.RE
|
|
.PP
|
|
shutdown\&.return cs
|
|
.RS 4
|
|
executes "force OB hack"
|
|
.RE
|
|
.PP
|
|
shutdown\&.return at:<nbr>
|
|
.RS 4
|
|
executes "hard hibernate" with <nbr>*6 minutes additional wakeup delay (<nbr> format is the same as of
|
|
\fBawd\fR
|
|
option)
|
|
.RE
|
|
.PP
|
|
shutdown\&.stayoff
|
|
.RS 4
|
|
executes "delayed poweroff"
|
|
.RE
|
|
.PP
|
|
load\&.off
|
|
.RS 4
|
|
executes "instant poweroff"
|
|
.RE
|
|
.sp
|
|
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\*(Aqre testing\&.
|
|
.sp
|
|
Other supported commands:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
load\&.on
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
test\&.panel\&.start
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
test\&.failure\&.start
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
test\&.battery\&.start
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
test\&.battery\&.stop
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
bypass\&.start
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
bypass\&.stop
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
calibrate\&.start
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
calibrate\&.stop
|
|
.RE
|
|
.SH "BUGS"
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
APC UPS models with both USB and serial ports require a power cycle when switching from USB communication to serial, and perhaps vice versa\&.
|
|
.SH "AUTHOR"
|
|
.sp
|
|
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>
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBnutupsdrv\fR(8), \fBups.conf\fR(5)
|
|
.SS "Internet resources:"
|
|
.sp
|
|
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/
|