1APCSMART(8) NUT Manual APCSMART(8)
2
6 apcsmart - Driver for American Power Conversion Smart Protocol UPS
7 equipment
8
10 apcsmart -h
11 apcsmart -a 'UPS_NAME' [-x option=value ...]
13 Note
15 This man page only documents the hardware-specific features of the
16 apcsmart driver. For information about the core driver, see
17 nutupsdrv(8).
18
20 The apcsmart driver should recognize (or at the very least work with)
21 majority of Smart-UPS models - which includes Smart-UPS, Matrix-UPS and
22 Back-UPS lineups, among few other ones.
23 Currently we can roughly divide APC hardware into 3 groups (note that
25 the division isn't strict by any means, and the borders between those
26 are pretty fuzzy):
27 [very] "old" models
29 These models usually have old APC logo, white color and no
30 programmable eeprom; You won't find them listed anywhere on APC’s
31 site either. The support for those will be usually based on
32 driver's compatibility tables, or if the model (firmware) is not
33 listed in those - the driver will try to follow the very basic
34 subset of features, while still trying to remain useful. Despite
35 "smart" tagname, they often tend to behave in pretty dumb way (see
36 the section below about shutdown behaviour).
37 Example models:
39 · Smart-UPS 2000I
41 · Smart-UPS 900I
43 "new" models
45 These models usually come from late 1990s / pre-2009 times. They
46 are often referred as "3rd. gen". For the most part, they have
47 programmable eeprom, report supported commands and capabilites, and
48 should work just fine with the apcsmart driver.
49 "microlink" models
51 WARNING: these are not natively supported by apcsmart (or apcupsd
52 for that matter, if you’re wondering). Around 2007 APC (now APC
53 Schneider) decided to go back to its proprietry roots and all the
54 new models (SMT, SMX, SURTD) use completely different protocol and
55 cables. If you purchased a new APC ups, that uses cable with rj45
56 on the one end, and db-9 on the other - then you have such model.
57 Your only option to support it through NUT is to purchase "legacy
58 communications card" - part #AP9620 (google 'AP9620' for more
59 details). Or if that's not an option, rely on official software.
60 Another thing to remember is that Smart protocol is not USB protocol.
62 If you have ups with both USB and serial ports, then depending on how
63 you connect it, you will need either apcsmart or usbhid-ups driver.
64
66 This driver expects to see a 940-0024C cable or a clone by default. You
67 can switch to the 940-0095B dual-mode cable support with the 'cable='
68 definition described below.
69 If your 940-0024C cable is broken or missing, use this diagram to build
71 a clone:
72 http://www.networkupstools.org/cables/940-0024C.jpg
74 You can specify alternate cable in ups.conf(5):
76 cable=940-0095B
78 Alternatively, you can also provide it on the command line using:
80 -x cable=940-0095B
82
84 APC hardware supports a lot of shutdown methods, that themselves can
85 differ in behaviour quite a bit, depending on the model.
86 S (soft hibernate)
88 This is most basic command present in probably all APC models. It
89 will hibernate the UPS, and subsequently wake it up when the mains
90 supply returns. The command doesn't work if UPS is running on
91 mains.
92 "old" models
94 The behaviour here is unfortunately pretty primitive - when the
95 power returns, the ups just wakes up. No grace periods, no min.
96 battery charge condition, etc. This is probably not what you
97 want.
98 "new" models
100 The behaviour here is as expected - the power is cut off after
101 the eeprom defined grace period. The ups will wake up when the
102 power returns, after the eeprom defined delay AND if the eeprom
103 defined min. battery charge level is met. The delay is counted
104 from the power's return.
105 CS (aka "force OB hack")
107 This is a trick to make UPS power down even if it's running on
108 mains. Immediately before issuing S, "simulate power failure" is
109 issued. The remaining behaviour is as in S case.
110 The name came from APC CS models, where such trick was used to
112 power down UPSes in consistent fashion using only S. It's better to
113 use @nnn command if your UPS supports it (and is not too old, see
114 below).
115 @nnn (hard hibernate)
117 This is basic command used to hibernate UPS regardless if it's
118 running on batteries or on mains. The option takes 3 digits
119 argument which can be used to specify additional wakeup delay (in 6
120 minute units).
121 "old" models
123 The behaviour is - unfortunately - similary primitive to S. The
124 ups unconditionally wakes up after nnn*6 minutes - it doesn't
125 care if the power returned ! If nnn = 000, then UPS will do
126 precisely nothing. On those models you're better specifying nnn
127 > 0, if you can estimate the kind of power problems that might
128 be happening in your environment. Another thing to consider
129 with "old" models - you might lose the connection with the ups,
130 until it wakes up (with S, the serial connection is kept
131 alive).
132 "new" models
134 All the usual variables defined in eeprom are respected (see
135 S). Additionally, if nnn > 0, the nnn*6 minutes are added to
136 eeprom defined delay. UPS will not power up if it's running on
137 batteries, contrary to what "old" models used to do - the
138 combined delay is counted from the moment of power return.
139 Supposedly there exist models that take 2 digits instead of 3. Just
141 in case, NUT also supports such variation. You have to provide
142 exactly 2 digits to trigger it (awd option, or argument to one of
143 the supported instant commands).
144 K (delayed poweroff)
146 This is permanent poweroff - the ups will not wake up
147 automatically. On newer units, it will respect applicable eeprom
148 variables.
149 Z (instant poweroff)
151 This is also permanent poweroff - the ups will not wake up
152 automatically. The poweroff is executed immediately.
153
155 There're 3 options used to control shutdown behaviour.
156 sdtype=[0-5]
158 This option takes a single digit (0-5) as an argument. See below
159 for details.
160 advorder=no|[0-4]+
162 This option takes string of digits as an argument. Methods listed
163 are tried in turn until one of them succeedes. Note that the
164 meaning of digits is different from sdtype. See below for details.
165 awd=[0-9]{1,3}
167 This option lets you specify additional wakeup delay used by @. If
168 you provide exactly 2 digits, the driver will try 2 digits
169 variation (see previous section for more info). Otherwise standard
170 3 digits variation is used. Note: the time unit is 6 minutes !
171 Keep in mind that sdtype and advorder are mutually exclusive. If
173 advorder is provided, sdtype is ignored. If advorder is set to 'no',
174 sdtype is used instead.
175 If nothing is provided, NUT will assume sdtype=0 - which is generally
177 fine for anything not too ancient or not too quirky.
178 SDTYPE
180 The values permitted are from 0 to 5. Only one can be specified.
181 Anything else will cause apcsmart to exit.
182 0
184 issue soft hibernate (S) if the ups is running on batteries,
185 otherwise issue hard hibernate (@)
186 1
188 issue soft hibernate (S) (if on batteries), and if it fails (or on
189 mains) - try hard hibernate (@)
190 2
192 issue instant poweroff (Z)
193 3
195 issue delayed poweroff (K)
196 4
198 issue "force OB hack" (CS)
199 5
201 issue hard hibernate (@)
202 Note
204 Hard hibernate's additional wakeup delay can be provided by awd.
205 ADVORDER
207 The argument is either a word 'no', or a string of 1 - 5 digits in [0 -
208 4] range. Each digit maps to the one of shutdown methods supported by
209 APC upses. Methods listed in this way are tried in order, until one of
210 them succedes.
211 If advorder is undefined or set to 'no', sdtype is used instead.
213 The mapping is as follows:
215 0 soft hibernate (S)
218 1 hard hibernate (@)
220 2 delayed poweroff (K)
222 3 instant poweroff (Z)
224 4 "force OB hack" (CS)
226 Note
229 Hard hibernate's additional wakeup delay can be provided by awd.
230
232 APC units - even if they report LB mode - will not go into shutdown
233 automatically. This gives us even more control with reference to "when
234 to actually shutdown psu". Since version 2.6.2, NUT supports ignorelb
235 option in driver's section of ups.conf(5). When such option is in
236 effect, the core driver will ignore LB state as reported by specific
237 driver and start shutdown basing the decision only on two conditions:
238 battery.charge < battery.charge.low
240 OR
242 battery.runtime < battery.runtime.low
244 Of course - if any of the variables are not available, the appropriate
246 condition is not checked. If you want to explicitly disable one of the
247 conditions, simply override the right hand variable causing the
248 condition to always evaluate to false (you can even provide negative
249 numbers).
250 APC upses don't have battery.charge.low - you will have to define it if
252 you want to use such condition (prefix the variable with override. or
253 default.).
254 "New" units have battery.runtime.low, but depending on battery quality,
256 firmware version, calibration and ups load - this variable can be
257 underestimated quite a bit - especially right after going into OB
258 state. This in turn can cause LB to be asserted, which under normal
259 conditions will cause NUT to initiate the shutdown. You might want to
260 disable this condition entirely, when relying on ignorelb option (this
261 was actually the main motivation behind introduction of such feature).
262 Simple example:
264 [apc]
266 ignorelb
267 override.battery.charge.low = 15
268 override.battery.runtime.low = -1
269 This would cause apcsmart to go into shutdown only if detected battery
271 charge < 15%. Runtime condition is always false in this example.
272 You could ask - why bother ? Well, the reason is already hinted above.
274 APC units can be very picky about the batteries, and their firmware can
275 underestimate the remaining runtime (especially right after going into
276 OB state). ignorelb option and override.* let you remain in control of
277 the ups, not ups in control of you.
278 Furthermore, this allows to specify conditions similary to how it’s
280 done in apcupsd daemon, so it should be welcome by people used to that
281 software.
282
284 The apcsmart driver exposes following instant commands:
285 shutdown.return
287 executes soft hibernate
288 shutdown.return cs
290 executes "force OB hack"
291 shutdown.return at:<nbr>
293 executes "hard hibernate" with <nbr>*6 minutes additional wakeup
294 delay (<nbr> format is the same as of awd option)
295 shutdown.stayoff
297 executes "delayed poweroff"
298 load.off
300 executes "instant poweroff"
301 All the above commands must be issued 2nd time to have any effect (no
303 less than 3 seconds, and no more than 15 seconds after the initial
304 call). Those commands are mostly useful for manual testing, when your
305 machine is not powered by the ups you're testing.
306 Other supported commands:
308 · load.on
310 · test.panel.start
312 · test.failure.start
314 · test.battery.start
316 · test.battery.stop
318 · bypass.start
320 · bypass.stop
322 · calibrate.start
324 · calibrate.stop
326
328 Some older APC UPS models return bogus data in the status register
329 during a front panel test. This is usually detected and discarded, but
330 some other unexpected values have occasionally slipped through.
331 APC UPS models with both USB and serial ports require a power cycle
333 when switching from USB communication to serial, and perhaps vice
334 versa.
335
337 Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
338 heavily on the original apcsmart driver by Russell Kroll). This driver
339 was called newapc for a time and was renamed in the 1.5 series. In
340 2.6.2 it was renamed to apcsmart-old, being superseded by updated
341 version with new features, which is maintained by Michal Soltys
342 <soltys@ziu.info>
343
345 nutupsdrv(8), ups.conf(5)
346 Internet resources:
348 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
349Network UPS Tools 09/15/2011 APCSMART(8)
