nut-debian/docs/man/apcsmart.8

'\" t
.\"     Title: apcsmart
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 09/15/2011
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools
.\"  Language: English
.\"
.TH "APCSMART" "8" "09/15/2011" "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\-0024C cable is broken or missing, use this diagram to build a clone:
.sp
http://www\&.networkupstools\&.org/cables/940\-0024C\&.jpg
.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\*(Aqre 3 options used to control 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/