This man page only documents the hardware\-specific features of the apcsmart driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
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\&.
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
.RS4
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
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Smart\-UPS 2000I
.RE
.sp
.RS4
.ien\{\
\h'-04'\(bu\h'+03'\c
.\}
.el\{\
.sp-1
.IP\(bu2.3
.\}
Smart\-UPS 900I
.RE
.RE
.PP
"new" models
.RS4
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
.RS4
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\&.
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\&.
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\&.
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
.RS4
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
.RS4
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")
.RS4
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)
.RS4
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
.RS4
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
.RS4
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)\&.
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)
.RS4
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]
.RS4
This option takes a single digit (0\-5) as an argument\&. See below for details\&.
.RE
.PP
\fBadvorder\fR=no|[0\-4]+
.RS4
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}
.RS4
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\&.
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\&.
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)\&.
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\&.
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\&.
The apcsmart driver exposes following instant commands:
.PP
shutdown\&.return
.RS4
executes soft hibernate
.RE
.PP
shutdown\&.return cs
.RS4
executes "force OB hack"
.RE
.PP
shutdown\&.return at:<nbr>
.RS4
executes "hard hibernate" with <nbr>*6 minutes additional wakeup delay (<nbr> format is the same as of
\fBawd\fR
option)
.RE
.PP
shutdown\&.stayoff
.RS4
executes "delayed poweroff"
.RE
.PP
load\&.off
.RS4
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\&.
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\&.
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>
