1APCSMART(8)                       NUT Manual                       APCSMART(8)
2
3
4

NAME

6       apcsmart - Driver for American Power Conversion Smart Protocol UPS
7       equipment
8

SYNOPSIS

10       apcsmart -h
11
12       apcsmart -a UPS_NAME [-x option=value ...]
13
14           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

SUPPORTED HARDWARE

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
24       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
28       [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
38           Example models:
39
40           •   Smart-UPS 2000I
41
42           •   Smart-UPS 900I
43
44       "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
50       "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
61       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
67           Example models:
68
69           •   Back-UPS BZ1200-BR
70
71           •   Back-UPS BZ2200BI-BR
72
73       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

CABLING

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
82       If your 940-xx24X cable is broken or missing, use this diagram to build
83       a clone:
84
85       http://www.networkupstools.org/cables.html#_940_0024c_clone
86
87           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
94       You can specify alternate cable in ups.conf(5):
95
96       cable=940-0095B
97
98       Alternatively, you can also provide it on the command line using:
99
100       -x cable=940-0095B
101

TTY MODES

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
109       ttymode=raw
110
111       Alternatively, you can also provide it on the command line using:
112
113       -x ttymode=raw
114
115           Note
116           Any other value will make the driver work in the canonical mode.
117

EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES

119       APC hardware supports a lot of shutdown methods, that themselves can
120       differ in behaviour quite a bit, depending on the model.
121
122       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
128           "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
134           "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
141       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
146           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
150           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
155       @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
161           "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
172           "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
179           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
184       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
189       Z (instant poweroff)
190           This is also permanent poweroff - the UPS will not wake up
191           automatically. The poweroff is executed immediately.
192

SHUTDOWN CONTROL BY NUT

194       There are three options used to control the shutdown behaviour.
195
196       sdtype=[0-5]
197           This option takes a single digit (0-5) as an argument. See below
198           for details.
199
200       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
205       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
211       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
215       If nothing is provided, NUT will assume sdtype=0 - which is generally
216       fine for anything not too ancient or not too quirky.
217
218   SDTYPE
219       The values permitted are from 0 to 5. Only one can be specified.
220       Anything else will cause apcsmart to exit.
221
222       0
223           issue soft hibernate (S) if the UPS is running on batteries,
224           otherwise issue hard hibernate (@)
225
226       1
227           issue soft hibernate (S) (if on batteries), and if it fails (or on
228           mains) - try hard hibernate (@)
229
230       2
231           issue instant poweroff (Z)
232
233       3
234           issue delayed poweroff (K)
235
236       4
237           issue "force OB hack" (CS)
238
239       5
240           issue hard hibernate (@)
241
242           Note
243           Hard hibernate’s additional wake-up delay can be provided by awd.
244
245   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
251       If advorder is undefined or set to no, sdtype is used instead.
252
253       The mapping is as follows:
254
255
256       0   soft hibernate (S)
257
258       1   hard hibernate (@)
259
260       2   delayed poweroff (K)
261
262       3   instant poweroff (Z)
263
264
265
266       4   "force OB hack" (CS)
267
268
269           Note
270           Hard hibernate’s additional wake-up delay can be provided by awd.
271

IGNORING LB STATE

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
280       battery.charge < battery.charge.low
281
282       OR
283
284       battery.runtime < battery.runtime.low
285
286       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
292       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
296       "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
304       Simple example:
305
306           [apc]
307               ignorelb
308               override.battery.charge.low = 15
309               override.battery.runtime.low = -1
310
311       This would cause apcsmart to go into shutdown only if detected battery
312       charge < 15%. Runtime condition is always false in this example.
313
314       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
320       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

SUPPORTED INSTANT COMMANDS

325       The apcsmart driver exposes following instant commands:
326
327       shutdown.return
328           executes soft hibernate
329
330       shutdown.return cs
331           executes "force OB hack"
332
333       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
337       shutdown.stayoff
338           executes "delayed poweroff"
339
340       load.off
341           executes "instant poweroff"
342
343       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
348       Other supported commands:
349
350       •   load.on
351
352       •   test.panel.start
353
354       •   test.failure.start
355
356       •   test.battery.start
357
358       •   test.battery.stop
359
360       •   bypass.start
361
362       •   bypass.stop
363
364       •   calibrate.start
365
366       •   calibrate.stop
367

PREVIOUS DRIVER VERSION

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

BUGS

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
380       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

AUTHORS AND HISTORY

385       Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
386       heavily on the original apcsmart driver by Russell Kroll).
387
388       This driver was called newapc for a time and was renamed in the 1.5
389       series.
390
391       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

SEE ALSO

396       nutupsdrv(8), ups.conf(5), usbhid-ups(8), solis(8)
397
398   Internet resources:
399       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
400
401
402
403Network UPS Tools 2.8.0           04/26/2022                       APCSMART(8)
Impressum