nut/docs/man/apcsmart.8

'\" t
.\"     Title: apcsmart
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/26/2022
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "APCSMART" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "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 \fIUPS_NAME\fR [\-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) the 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 four groups (note that the division isn\(cqt 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\(cqt find them listed anywhere on APC\(cqs site either\&. The support for those will be usually based on driver\(cqs 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 capabilities, and should work just fine with the apcsmart driver\&.
.RE
.PP
"microlink" models
.RS 4
WARNING: these are not
\fInatively\fR
supported by
\fBapcsmart\fR
(or
\fBapcupsd\fR, for that matter, if you\(cqre wondering)\&. Around 2007, APC (now APC Schneider) decided to go back to its proprietary 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 a "legacy communications card" \- part #AP9620 (google
\fIAP9620\fR
for more details)\&. Or if that\(cqs not an option, rely on official software\&.
.RE
.PP
Microsol models
.RS 4
Several Microsol serial models sold in Brazil have been rebranded as APC Back\-UPS, and the model numbers tend to start with "BZ"\&. If you have one of these "Nobreaks", they will not work with the
\fBapcsmart\fR
driver \- please see the
\fBsolis\fR(8)
driver instead\&.
.PP
\fBExample models:\fR
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Back\-UPS BZ1200\-BR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Back\-UPS BZ2200BI\-BR
.RE
.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 \fIcable=\fR 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 "TTY MODES"
.sp
By default the driver works in canonical mode, but it proved to be a problem in Windows systems\&. Furthermore there\(cqs a possibility of some obscure serial cards or serial\-USB converters that could cause problems as well\&. You can use \fIttymode=\fR option to force non\-canonical discipline in \fBups.conf\fR(5):
.sp
\fBttymode\fR=raw
.sp
Alternatively, you can also provide it on the command line using:
.sp
\-x \fBttymode\fR=raw
.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
Any other value will make the driver work in the canonical mode\&.
.sp .5v
.RE
.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\(cqt work if the 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\(cqs return\&.
.RE
.RE
.PP
\fBCS\fR (aka "force OB hack")
.RS 4
This is a trick to make UPS power down even if it\(cqs running on mains\&. Immediately before issuing
\fBS\fR, "simulate power failure" is issued\&. The remaining behaviour is as in
\fBS\fR
case\&.
.sp
There\(cqs a delay between "simulate power failure" and
\fBS\fR
\- by default set to 3\&.5s\&. You can control it through
\fBcshdelay\fR
option (allowed values are from 0 to 9\&.9)\&.
.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\(cqs 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\(cqs running on batteries or on mains\&. The option takes 3 digits argument which can be used to specify additional wake\-up delay (in 6 minute units)\&.
.PP
"old" models:
.RS 4
The behaviour is \- unfortunately \- similarly primitive to
\fBS\fR\&. The UPS unconditionally wakes up after nnn*6 minutes \-
\fBit doesn\(cqt care if the power returned !\fR
If nnn = 000, then UPS will do precisely nothing\&. On those models you\(cqre 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\(cqs 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 succeeds\&. 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 wake\-up 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 \fIno\fR, \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\(cqs additional wake\-up delay can be provided by \fBawd\fR\&.
.sp .5v
.RE
.SS "ADVORDER"
.sp
The argument is either a word \fIno\fR, 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 succeeds\&.
.sp
If \fBadvorder\fR is undefined or set to \fIno\fR, \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\(cqs additional wake\-up 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\(cqs 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\(cqt 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 similarly 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 wake\-up 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\(cqre 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 "PREVIOUS DRIVER VERSION"
.sp
Previous driver is still available as \fBapcsmart\-old\fR, should there be any need to use earlier version (bugs, incompatibilities with new functionality, etc\&.)\&. In due time, \fBapcsmart\-old\fR will be phased out completely, but this won\(cqt happen until the new version gets solid exposure with no pending issues\&.
.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 "AUTHORS AND HISTORY"
.sp
Nigel Metheringham <Nigel\&.Metheringham@Intechnology\&.co\&.uk> (drawing heavily on the original apcsmart driver by Russell Kroll)\&.
.sp
This driver was called newapc for a time and was renamed in the 1\&.5 series\&.
.sp
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), \fBusbhid-ups\fR(8), \fBsolis\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/