7
apcsmart - Driver for American Power Conversion Smart Protocol UPS equipment
14
*apcsmart* -a \'UPS_NAME' [-x option=value ...]
16
NOTE: This man page only documents the hardware-specific features of the
17
apcsmart driver. For information about the core driver, see
24
The apcsmart driver should recognize (or at the very least work with) majority
25
of Smart-UPS models - which includes Smart-UPS, Matrix-UPS and Back-UPS lineups,
28
Currently we can roughly divide APC hardware into 3 groups (note that the
29
division isn\'t strict by any means, and the borders between those are pretty fuzzy):
32
These models usually have old APC logo, white color and _no_ programmable
33
eeprom; You won\'t find them listed anywhere on APC's site either. The support
34
for those will be usually based on driver\'s compatibility tables, or if the
35
model (firmware) is not listed in those - the driver will try to follow the very
36
basic subset of features, while still trying to remain useful. Despite
37
"smart" tagname, they often tend to behave in pretty dumb way (see the
38
section below about shutdown behaviour).
47
These models usually come from late 1990s / pre-2009 times. They are often
48
referred as "3rd. gen". For the most part, they have programmable eeprom,
49
report supported commands and capabilites, and should work just fine with the
53
WARNING: these are not _natively_ supported by apcsmart (or apcupsd for that
54
matter, if you\'re wondering). Around 2007 APC (now APC Schneider) decided to
55
go back to its proprietry roots and all the new models (SMT, SMX, SURTD) use
56
completely different protocol and cables. If you purchased a new APC UPS,
57
that uses cable with rj45 on the one end, and db-9 on the other - then you
58
have such model. Your only option to support it through *NUT* is to
59
purchase "legacy communications card" - part #AP9620 (google \'AP9620' for
60
more details). Or if that\'s not an option, rely on official software.
62
Another thing to remember is that Smart protocol is not USB protocol. If you
63
have UPS with both USB and serial ports, then depending on how you connect it,
64
you will need either apcsmart or usbhid-ups driver.
69
This driver expects to see a 940-0024C cable or a clone by default. You
70
can switch to the 940-0095B dual-mode cable support with the \'cable='
71
definition described below.
73
If your 940-xx24X cable is broken or missing, use this diagram to build
76
http://www.networkupstools.org/cables.html#_940_0024c_clone
78
NOTE: The "xx" is either "00" for a short cable, or the number of feet
79
of a longer cable. The "X" is a letter representing the minor revision
80
of the physical cable and its connectors ("C" and "E" are commonly found
81
revisions). All minor revisions should use the same pin-outs and
84
You can specify alternate cable in linkman:ups.conf[5]:
88
Alternatively, you can also provide it on the command line using:
95
By default the driver works in canonical mode, but it showed to be a problem in
96
windows systems. Furthermore there's a possibility of some obscure serial cards
97
or serial-usb convertes that could cause problems as well. You can use
98
\'ttymode=' option to force non-canonical discipline in linkman:ups.conf[5]:
102
Alternatively, you can also provide it on the command line using:
106
NOTE: Any other value will make the driver work in the canonical mode.
108
EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES
109
------------------------------------------------------
111
APC hardware supports a lot of shutdown methods, that themselves can differ in
112
behaviour quite a bit, depending on the model.
114
*S* (soft hibernate)::
115
This is most basic command present in probably all APC models. It will
116
hibernate the UPS, and subsequently wake it up when the mains supply
117
returns. *The command doesn\'t work if UPS is running on mains.*
120
The behaviour here is unfortunately pretty primitive - when the power
121
returns, the UPS just wakes up. No grace periods, no min. battery
122
charge condition, etc. This is probably not what you want.
125
The behaviour here is as expected - the power is cut off after the
126
eeprom defined grace period. The UPS will wake up when the power
127
returns, after the eeprom defined delay AND if the eeprom defined min.
128
battery charge level is met. The delay is counted from the power\'s
131
*CS* (aka "force OB hack")::
132
This is a trick to make UPS power down even if it\'s running on mains.
133
Immediately before issuing *S*, "simulate power failure" is issued. The
134
remaining behaviour is as in *S* case.
136
The name came from APC CS models, where such trick was used to power down
137
UPSes in consistent fashion using only *S*. It\'s better to use *@nnn*
138
command if your UPS supports it (and is not too old, see below).
140
*@nnn* (hard hibernate)::
141
This is basic command used to hibernate UPS regardless if it\'s
142
running on batteries or on mains. The option takes 3 digits argument which
143
can be used to specify additional wakeup delay (in 6 minute units).
147
The behaviour is - unfortunately - similary primitive to *S*. The UPS
148
unconditionally wakes up after $$nnn*6$$ minutes - *it doesn\'t care if the
149
power returned !* If nnn = 000, then UPS will do precisely nothing. On
150
those models you\'re better specifying nnn > 0, if you can estimate
151
the kind of power problems that might be happening in your environment.
152
Another thing to consider with "old" models - you might lose the
153
connection with the UPS, until it wakes up (with *S*, the serial
154
connection is kept alive).
157
All the usual variables defined in eeprom are respected (see *S*).
158
Additionally, if nnn > 0, the $$nnn*6$$ minutes are added to eeprom
159
defined delay. UPS will not power up if it\'s running on batteries,
160
contrary to what "old" models used to do - the combined delay is counted
161
from the moment of power return.
164
Supposedly there exist models that take 2 digits instead of 3. Just in case,
165
NUT also supports such variation. You have to provide exactly 2 digits to
166
trigger it (*awd* option, or argument to one of the supported instant commands).
168
*K* (delayed poweroff)::
169
This is permanent poweroff - the UPS will not wake up automatically. On
170
newer units, it will respect applicable eeprom variables.
172
*Z* (instant poweroff)::
173
This is also permanent poweroff - the UPS will not wake up automatically.
174
The poweroff is executed immediately.
176
SHUTDOWN CONTROL BY NUT
177
-----------------------
179
There are three options used to control the shutdown behaviour.
182
This option takes a single digit (0-5) as an argument. See below for
185
*advorder*=no|[0-4]+::
186
This option takes string of digits as an argument. Methods listed are tried
187
in turn until one of them succeedes. Note that the meaning of digits is
188
different from *sdtype*. See below for details.
191
This option lets you specify additional wakeup delay used by *@*. If you
192
provide exactly 2 digits, the driver will try 2 digits variation (see
193
previous section for more info). Otherwise standard 3 digits variation is
194
used. *Note: the time unit is 6 minutes !*
196
Keep in mind that *sdtype* and *advorder* are mutually exclusive. If *advorder*
197
is provided, *sdtype* is ignored. If *advorder* is set to \'no', *sdtype* is
200
If nothing is provided, *NUT* will assume *sdtype*=0 - which is generally fine
201
for anything not too ancient or not too quirky.
206
The values permitted are from 0 to 5. Only one can be specified. Anything else
207
will cause apcsmart to exit.
210
issue soft hibernate (*S*) if the UPS is running on batteries, otherwise issue
213
issue soft hibernate (*S*) (if on batteries), and if it fails (or on mains) -
214
try hard hibernate (*@*)
216
issue instant poweroff (*Z*)
218
issue delayed poweroff (*K*)
220
issue "force OB hack" (*CS*)
222
issue hard hibernate (*@*)
224
NOTE: Hard hibernate\'s additional wakeup delay can be provided by *awd*.
229
The argument is either a word \'no', or a string of 1 - 5 digits in [0 - 4]
230
range. Each digit maps to the one of shutdown methods supported by APC UPSes.
231
Methods listed in this way are tried in order, until one of them succedes.
233
If *advorder* is undefined or set to \'no', *sdtype* is used instead.
235
The mapping is as follows:
238
0:: soft hibernate (*S*)
239
1:: hard hibernate (*@*)
240
2:: delayed poweroff (*K*)
241
3:: instant poweroff (*Z*)
242
4:: "force OB hack" (*CS*)
244
NOTE: Hard hibernate\'s additional wakeup delay can be provided by *awd*.
249
APC units - even if they report LB mode - will not go into shutdown
250
automatically. This gives us even more control with reference to "when to
251
actually shutdown psu". Since version 2.6.2, NUT supports *ignorelb* option in
252
driver\'s section of linkman:ups.conf[5]. When such option is in effect,
253
the core driver will ignore LB state as reported by specific driver and
254
start shutdown basing the decision _only_ on two conditions:
256
battery.charge < battery.charge.low
260
battery.runtime < battery.runtime.low
262
Of course - if any of the variables are not available, the appropriate condition
263
is not checked. If you want to explicitly disable one of the conditions, simply
264
override the right hand variable causing the condition to always evaluate to
265
false (you can even provide negative numbers).
267
APC UPSes don\'t have battery.charge.low - you will have to define it if you want
268
to use such condition (prefix the variable with override. or default.).
270
"New" units have battery.runtime.low, but depending on battery quality, firmware
271
version, calibration and UPS load - this variable can be underestimated quite a bit -
272
especially right after going into OB state. This in turn can cause LB to be
273
asserted, which under normal conditions will cause *NUT* to initiate the
274
shutdown. You might want to disable this condition entirely, when relying on
275
*ignorelb* option (this was actually the main motivation behind introduction of
284
override.battery.charge.low = 15
285
override.battery.runtime.low = -1
288
This would cause apcsmart to go into shutdown _only_ if detected battery charge
289
< 15%. Runtime condition is always false in this example.
291
You could ask - why bother ? Well, the reason is already hinted above. APC units
292
can be very picky about the batteries, and their firmware can underestimate the
293
remaining runtime (especially right after going into OB state). *ignorelb*
294
option and *$$override.*$$* let you remain in control of the UPS, not UPS in control
297
Furthermore, this allows to specify conditions similary to how it's done in
298
apcupsd daemon, so it should be welcome by people used to that software.
301
SUPPORTED INSTANT COMMANDS
302
--------------------------
304
The apcsmart driver exposes following instant commands:
307
executes soft hibernate
309
executes "force OB hack"
310
shutdown.return at:<nbr>::
311
executes "hard hibernate" with $$<nbr>*6$$ minutes additional wakeup delay (<nbr> format
312
is the same as of *awd* option)
314
executes "delayed poweroff"
316
executes "instant poweroff"
318
All the above commands must be issued 2nd time to have any effect (no less than 3
319
seconds, and no more than 15 seconds after the initial call). Those commands are
320
mostly useful for manual testing, when your machine is not powered by the UPS
323
Other supported commands:
335
PREVIOUS DRIVER VERSION
336
-----------------------
338
Previous driver is still available as apcsmart-old - should there be any need to
339
use earlier version (bugs, incompatiblities with new functionality, etc.). In
340
due time apcsmart-old will be phased out completely, but this won't happen until
341
the new version gets solid exposure with no pending issues.
346
Some older APC UPS models return bogus data in the status register during
347
a front panel test. This is usually detected and discarded, but some
348
other unexpected values have occasionally slipped through.
350
APC UPS models with both USB and serial ports require a power cycle when
351
switching from USB communication to serial, and perhaps vice versa.
356
Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
357
heavily on the original apcsmart driver by Russell Kroll). This driver
358
was called newapc for a time and was renamed in the 1.5 series. In 2.6.2
359
it was renamed to apcsmart-old, being superseded by updated version with
360
new features, which is maintained by Michal Soltys <soltys@ziu.info>
365
linkman:nutupsdrv[8], linkman:ups.conf[5]
369
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
371
// vim: tw=80 ai si ts=8 sts=4 sw=4 et :
added
removed
docs/man/apcsmart.txt
