'\" 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: 02/19/2024
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.1
.\"  Language: English
.\"
.TH "APCSMART" "8" "02/19/2024" "Network UPS Tools 2\&.8\&.1" "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 \(em 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 \(em 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 to 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 as of this writing by
\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 \(em that uses cable with RJ45 on the one end, and DB\-9 on the other \(em then you have such model\&. Your only option to support it through
\fBNUT\fR
is to purchase a "legacy communications card" \(em  part #AP9620 (google
\fIAP9620\fR
for more details)\&. Or if that\(cqs not an option, rely on official software\&.

UPDATE: later releases of
\fBapcupsd\fR
claimed support for new APC protocols, so it is worth checking if
\fBapcupsd\fR
software would work with your device, and
\fBapcupsd\-ups\fR
NUT driver would handle it as part of NUT\-managed ecosystem\&.
.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 \(em 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
https://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 \(em 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 \(em 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 \(em unfortunately \(em 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 \(em 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 \(em 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 \(em 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 \(em 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 \(em 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) \(em 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 \(em even if they report LB mode \(em 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 \(em 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 \(em 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 \(em this variable can be underestimated quite a bit \(em 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 \(em 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: https://www\&.networkupstools\&.org/