APCSMART(8)                       NUT Manual                       APCSMART(8)



NAME
       apcsmart - Driver for American Power Conversion Smart Protocol UPS
       equipment

SYNOPSIS
       apcsmart -h

       apcsmart -a 'UPS_NAME' [-x option=value ...]

           Note
           This man page only documents the hardware-specific features of the
           apcsmart driver. For information about the core driver, see
           nutupsdrv(8).

SUPPORTED HARDWARE
       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't strict by any means, and the borders between those
       are pretty fuzzy):

       [very] "old" models
           These models usually have old APC logo, white color and no
           programmable eeprom; You won't find them listed anywhere on APC's
           site either. The support for those will be usually based on
           driver's 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).

           Example models:

           o   Smart-UPS 2000I

           o   Smart-UPS 900I

       "new" models
           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.

       "microlink" models
           WARNING: these are not natively supported by apcsmart (or apcupsd
           for that matter, if you're 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 NUT is to purchase "legacy
           communications card" - part #AP9620 (google 'AP9620' for more
           details). Or if that's 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.

CABLING
       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 'cable='
       definition described below.

       If your 940-xx24X cable is broken or missing, use this diagram to build
       a clone:

       http://www.networkupstools.org/cables.html#_940_0024c_clone

           Note
           The "xx" is either "00" for a short cable, or the number of feet of
           a longer cable. The "X" is a letter representing the minor revision
           of the physical cable and its connectors ("C" and "E" are commonly
           found revisions). All minor revisions should use the same pin-outs
           and wiring.

       You can specify alternate cable in ups.conf(5):

       cable=940-0095B

       Alternatively, you can also provide it on the command line using:

       -x cable=940-0095B

EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES
       APC hardware supports a lot of shutdown methods, that themselves can
       differ in behaviour quite a bit, depending on the model.

       S (soft hibernate)
           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.  The command doesn't work if UPS is running on
           mains.

           "old" models
               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.

           "new" models
               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's return.

       CS (aka "force OB hack")
           This is a trick to make UPS power down even if it's running on
           mains. Immediately before issuing S, "simulate power failure" is
           issued. The remaining behaviour is as in S case.

           The name came from APC CS models, where such trick was used to
           power down UPSes in consistent fashion using only S. It's better to
           use @nnn command if your UPS supports it (and is not too old, see
           below).

       @nnn (hard hibernate)
           This is basic command used to hibernate UPS regardless if it's
           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).

           "old" models
               The behaviour is - unfortunately - similary primitive to S. The
               UPS unconditionally wakes up after nnn*6 minutes - it doesn't
               care if the power returned !  If nnn = 000, then UPS will do
               precisely nothing. On those models you're 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 S, the serial connection is kept
               alive).

           "new" models
               All the usual variables defined in eeprom are respected (see
               S). Additionally, if nnn > 0, the nnn*6 minutes are added to
               eeprom defined delay. UPS will not power up if it's running on
               batteries, contrary to what "old" models used to do - the
               combined delay is counted from the moment of power return.

           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 (awd option, or argument to one of
           the supported instant commands).

       K (delayed poweroff)
           This is permanent poweroff - the UPS will not wake up
           automatically. On newer units, it will respect applicable eeprom
           variables.

       Z (instant poweroff)
           This is also permanent poweroff - the UPS will not wake up
           automatically. The poweroff is executed immediately.

SHUTDOWN CONTROL BY NUT
       There are three options used to control the shutdown behaviour.

       sdtype=[0-5]
           This option takes a single digit (0-5) as an argument. See below
           for details.

       advorder=no|[0-4]+
           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 sdtype. See below for details.

       awd=[0-9]{1,3}
           This option lets you specify additional wakeup delay used by @. 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.  Note: the time unit is 6 minutes !

       Keep in mind that sdtype and advorder are mutually exclusive. If
       advorder is provided, sdtype is ignored. If advorder is set to 'no',
       sdtype is used instead.

       If nothing is provided, NUT will assume sdtype=0 - which is generally
       fine for anything not too ancient or not too quirky.

   SDTYPE
       The values permitted are from 0 to 5. Only one can be specified.
       Anything else will cause apcsmart to exit.

       0
           issue soft hibernate (S) if the UPS is running on batteries,
           otherwise issue hard hibernate (@)

       1
           issue soft hibernate (S) (if on batteries), and if it fails (or on
           mains) - try hard hibernate (@)

       2
           issue instant poweroff (Z)

       3
           issue delayed poweroff (K)

       4
           issue "force OB hack" (CS)

       5
           issue hard hibernate (@)

           Note
           Hard hibernate's additional wakeup delay can be provided by awd.

   ADVORDER
       The argument is either a word 'no', 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.

       If advorder is undefined or set to 'no', sdtype is used instead.

       The mapping is as follows:


       0   soft hibernate (S)

       1   hard hibernate (@)

       2   delayed poweroff (K)

       3   instant poweroff (Z)

       4   "force OB hack" (CS)


           Note
           Hard hibernate's additional wakeup delay can be provided by awd.

IGNORING LB STATE
       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 ignorelb
       option in driver's section of ups.conf(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 only on two conditions:

       battery.charge < battery.charge.low

       OR

       battery.runtime < battery.runtime.low

       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).

       APC UPSes don't have battery.charge.low - you will have to define it if
       you want to use such condition (prefix the variable with override. or
       default.).

       "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 NUT to initiate the shutdown. You might want to
       disable this condition entirely, when relying on ignorelb option (this
       was actually the main motivation behind introduction of such feature).

       Simple example:

           [apc]
               ignorelb
               override.battery.charge.low = 15
               override.battery.runtime.low = -1

       This would cause apcsmart to go into shutdown only if detected battery
       charge < 15%. Runtime condition is always false in this example.

       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). ignorelb option and override.* let you remain in control of
       the UPS, not UPS in control of you.

       Furthermore, this allows to specify conditions similary to how it's
       done in apcupsd daemon, so it should be welcome by people used to that
       software.

SUPPORTED INSTANT COMMANDS
       The apcsmart driver exposes following instant commands:

       shutdown.return
           executes soft hibernate

       shutdown.return cs
           executes "force OB hack"

       shutdown.return at:<nbr>
           executes "hard hibernate" with <nbr>*6 minutes additional wakeup
           delay (<nbr> format is the same as of awd option)

       shutdown.stayoff
           executes "delayed poweroff"

       load.off
           executes "instant poweroff"

       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're testing.

       Other supported commands:

       o   load.on

       o   test.panel.start

       o   test.failure.start

       o   test.battery.start

       o   test.battery.stop

       o   bypass.start

       o   bypass.stop

       o   calibrate.start

       o   calibrate.stop

BUGS
       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.

       APC UPS models with both USB and serial ports require a power cycle
       when switching from USB communication to serial, and perhaps vice
       versa.

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

SEE ALSO
       nutupsdrv(8), ups.conf(5)

   Internet resources:
       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/



Network UPS Tools                 05/21/2012                       APCSMART(8)
