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 the majority of Smart-UPS models - which includes Smart-UPS, Matrix-UPS
22 and Back-UPS lineups, among few other ones.
23 Currently, we can roughly divide APC hardware into four groups (note
25 that the division isn’t strict by any means, and the borders between
26 those 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 capabilities,
48 and 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 proprietary 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 a "legacy
58 communications card" - part #AP9620 (google AP9620 for more
59 details). Or if that’s not an option, rely on official software.
60 Microsol models
62 Several Microsol serial models sold in Brazil have been rebranded
63 as APC Back-UPS, and the model numbers tend to start with "BZ". If
64 you have one of these "Nobreaks", they will not work with the
65 apcsmart driver - please see the solis(8) driver instead.
66 Example models:
68 • Back-UPS BZ1200-BR
70 • Back-UPS BZ2200BI-BR
72 Another thing to remember is that Smart protocol is not USB protocol.
74 If you have UPS with both USB and serial ports, then depending on how
75 you connect it, you will need either apcsmart or usbhid-ups driver.
76
78 This driver expects to see a 940-0024C cable or a clone by default. You
79 can switch to the 940-0095B dual-mode cable support with the cable=
80 definition described below.
81 If your 940-xx24X cable is broken or missing, use this diagram to build
83 a clone:
84 http://www.networkupstools.org/cables.html#_940_0024c_clone
86 Note
88 The "xx" is either "00" for a short cable, or the number of feet of
89 a longer cable. The "X" is a letter representing the minor revision
90 of the physical cable and its connectors ("C" and "E" are commonly
91 found revisions). All minor revisions should use the same pin-outs
92 and wiring.
93 You can specify alternate cable in ups.conf(5):
95 cable=940-0095B
97 Alternatively, you can also provide it on the command line using:
99 -x cable=940-0095B
101
103 By default the driver works in canonical mode, but it proved to be a
104 problem in Windows systems. Furthermore there’s a possibility of some
105 obscure serial cards or serial-USB converters that could cause problems
106 as well. You can use ttymode= option to force non-canonical discipline
107 in ups.conf(5):
108 ttymode=raw
110 Alternatively, you can also provide it on the command line using:
112 -x ttymode=raw
114 Note
116 Any other value will make the driver work in the canonical mode.
117
119 APC hardware supports a lot of shutdown methods, that themselves can
120 differ in behaviour quite a bit, depending on the model.
121 S (soft hibernate)
123 This is most basic command present in probably all APC models. It
124 will hibernate the UPS, and subsequently wake it up when the mains
125 supply returns. The command doesn’t work if the UPS is running on
126 mains.
127 "old" models:
129 The behaviour here is unfortunately pretty primitive - when the
130 power returns, the UPS just wakes up. No grace periods, no min.
131 battery charge condition, etc. This is probably not what you
132 want.
133 "new" models:
135 The behaviour here is as expected - the power is cut off after
136 the EEPROM defined grace period. The UPS will wake up when the
137 power returns, after the EEPROM defined delay AND if the EEPROM
138 defined min. battery charge level is met. The delay is counted
139 from the power’s return.
140 CS (aka "force OB hack")
142 This is a trick to make UPS power down even if it’s running on
143 mains. Immediately before issuing S, "simulate power failure" is
144 issued. The remaining behaviour is as in S case.
145 There’s a delay between "simulate power failure" and S - by default
147 set to 3.5s. You can control it through cshdelay option (allowed
148 values are from 0 to 9.9).
149 The name came from APC CS models, where such trick was used to
151 power down UPSes in consistent fashion using only S. It’s better to
152 use @nnn command if your UPS supports it (and is not too old, see
153 below).
154 @nnn (hard hibernate)
156 This is basic command used to hibernate UPS regardless if it’s
157 running on batteries or on mains. The option takes 3 digits
158 argument which can be used to specify additional wake-up delay (in
159 6 minute units).
160 "old" models:
162 The behaviour is - unfortunately - similarly primitive to S.
163 The UPS unconditionally wakes up after nnn*6 minutes - it
164 doesn’t care if the power returned ! If nnn = 000, then UPS
165 will do precisely nothing. On those models you’re better
166 specifying nnn > 0, if you can estimate the kind of power
167 problems that might be happening in your environment. Another
168 thing to consider with "old" models - you might lose the
169 connection with the UPS, until it wakes up (with S, the serial
170 connection is kept alive).
171 "new" models:
173 All the usual variables defined in EEPROM are respected (see
174 S). Additionally, if nnn > 0, the nnn*6 minutes are added to
175 EEPROM defined delay. UPS will not power up if it’s running on
176 batteries, contrary to what "old" models used to do - the
177 combined delay is counted from the moment of power return.
178 Supposedly there exist models that take 2 digits instead of 3. Just
180 in case, NUT also supports such variation. You have to provide
181 exactly 2 digits to trigger it (awd option, or argument to one of
182 the supported instant commands).
183 K (delayed poweroff)
185 This is permanent poweroff - the UPS will not wake up
186 automatically. On newer units, it will respect applicable EEPROM
187 variables.
188 Z (instant poweroff)
190 This is also permanent poweroff - the UPS will not wake up
191 automatically. The poweroff is executed immediately.
192
194 There are three options used to control the shutdown behaviour.
195 sdtype=[0-5]
197 This option takes a single digit (0-5) as an argument. See below
198 for details.
199 advorder=no|[0-4]+
201 This option takes string of digits as an argument. Methods listed
202 are tried in turn until one of them succeeds. Note that the meaning
203 of digits is different from sdtype. See below for details.
204 awd=[0-9]{1,3}
206 This option lets you specify additional wake-up delay used by @. If
207 you provide exactly 2 digits, the driver will try 2 digits
208 variation (see previous section for more info). Otherwise standard
209 3 digits variation is used. Note: the time unit is 6 minutes !
210 Keep in mind that sdtype and advorder are mutually exclusive. If
212 advorder is provided, sdtype is ignored. If advorder is set to no,
213 sdtype is used instead.
214 If nothing is provided, NUT will assume sdtype=0 - which is generally
216 fine for anything not too ancient or not too quirky.
217 SDTYPE
219 The values permitted are from 0 to 5. Only one can be specified.
220 Anything else will cause apcsmart to exit.
221 0
223 issue soft hibernate (S) if the UPS is running on batteries,
224 otherwise issue hard hibernate (@)
225 1
227 issue soft hibernate (S) (if on batteries), and if it fails (or on
228 mains) - try hard hibernate (@)
229 2
231 issue instant poweroff (Z)
232 3
234 issue delayed poweroff (K)
235 4
237 issue "force OB hack" (CS)
238 5
240 issue hard hibernate (@)
241 Note
243 Hard hibernate’s additional wake-up delay can be provided by awd.
244 ADVORDER
246 The argument is either a word no, or a string of 1 - 5 digits in [0 -
247 4] range. Each digit maps to the one of shutdown methods supported by
248 APC UPSes. Methods listed in this way are tried in order, until one of
249 them succeeds.
250 If advorder is undefined or set to no, sdtype is used instead.
252 The mapping is as follows:
254 0 soft hibernate (S)
257 1 hard hibernate (@)
259 2 delayed poweroff (K)
261 3 instant poweroff (Z)
263 4 "force OB hack" (CS)
267 Note
270 Hard hibernate’s additional wake-up delay can be provided by awd.
271
273 APC units - even if they report LB mode - will not go into shutdown
274 automatically. This gives us even more control with reference to "when
275 to actually shutdown PSU". Since version 2.6.2, NUT supports ignorelb
276 option in driver’s section of ups.conf(5). When such option is in
277 effect, the core driver will ignore LB state as reported by specific
278 driver and start shutdown basing the decision only on two conditions:
279 battery.charge < battery.charge.low
281 OR
283 battery.runtime < battery.runtime.low
285 Of course - if any of the variables are not available, the appropriate
287 condition is not checked. If you want to explicitly disable one of the
288 conditions, simply override the right hand variable causing the
289 condition to always evaluate to false (you can even provide negative
290 numbers).
291 APC UPSes don’t have battery.charge.low - you will have to define it if
293 you want to use such condition (prefix the variable with override. or
294 default.).
295 "New" units have battery.runtime.low, but depending on battery quality,
297 firmware version, calibration and UPS load - this variable can be
298 underestimated quite a bit - especially right after going into OB
299 state. This in turn can cause LB to be asserted, which under normal
300 conditions will cause NUT to initiate the shutdown. You might want to
301 disable this condition entirely, when relying on ignorelb option (this
302 was actually the main motivation behind introduction of such feature).
303 Simple example:
305 [apc]
307 ignorelb
308 override.battery.charge.low = 15
309 override.battery.runtime.low = -1
310 This would cause apcsmart to go into shutdown only if detected battery
312 charge < 15%. Runtime condition is always false in this example.
313 You could ask - why bother ? Well, the reason is already hinted above.
315 APC units can be very picky about the batteries, and their firmware can
316 underestimate the remaining runtime (especially right after going into
317 OB state). ignorelb option and override.* let you remain in control of
318 the UPS, not UPS in control of you.
319 Furthermore, this allows to specify conditions similarly to how it’s
321 done in apcupsd daemon, so it should be welcome by people used to that
322 software.
323
325 The apcsmart driver exposes following instant commands:
326 shutdown.return
328 executes soft hibernate
329 shutdown.return cs
331 executes "force OB hack"
332 shutdown.return at:<nbr>
334 executes "hard hibernate" with <nbr>*6 minutes additional wake-up
335 delay (<nbr> format is the same as of awd option)
336 shutdown.stayoff
338 executes "delayed poweroff"
339 load.off
341 executes "instant poweroff"
342 All the above commands must be issued 2nd time to have any effect (no
344 less than 3 seconds, and no more than 15 seconds after the initial
345 call). Those commands are mostly useful for manual testing, when your
346 machine is not powered by the UPS you’re testing.
347 Other supported commands:
349 • load.on
351 • test.panel.start
353 • test.failure.start
355 • test.battery.start
357 • test.battery.stop
359 • bypass.start
361 • bypass.stop
363 • calibrate.start
365 • calibrate.stop
367
369 Previous driver is still available as apcsmart-old, should there be any
370 need to use earlier version (bugs, incompatibilities with new
371 functionality, etc.). In due time, apcsmart-old will be phased out
372 completely, but this won’t happen until the new version gets solid
373 exposure with no pending issues.
374
376 Some older APC UPS models return bogus data in the status register
377 during a front panel test. This is usually detected and discarded, but
378 some other unexpected values have occasionally slipped through.
379 APC UPS models with both USB and serial ports require a power cycle
381 when switching from USB communication to serial, and perhaps vice
382 versa.
383
385 Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
386 heavily on the original apcsmart driver by Russell Kroll).
387 This driver was called newapc for a time and was renamed in the 1.5
389 series.
390 In 2.6.2 it was renamed to apcsmart-old, being superseded by updated
392 version with new features, which is maintained by Michal Soltys
393 <soltys@ziu.info>
394
396 nutupsdrv(8), ups.conf(5), usbhid-ups(8), solis(8)
397 Internet resources:
399 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
400Network UPS Tools 2.8.0 04/26/2022 APCSMART(8)