NAME¶

apcsmart - Driver for American Power Conversion Smart Protocol UPS equipment

SYNOPSIS¶

apcsmart -h

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

SUPPORTED HARDWARE¶

The apcsmart driver should recognize (or at the very least, work with) the 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 four groups (note that the division isn’t strict by any means, and the borders between those are pretty fuzzy):

[very] "old" models

"new" models

"microlink" models

Microsol models

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:

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

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

TTY MODES¶

By default the driver works in canonical mode, but it proved to be a problem in Windows systems. Furthermore there’s a possibility of some obscure serial cards or serial-USB converters that could cause problems as well. You can use ttymode= option to force non-canonical discipline in ups.conf(5):

ttymode=raw

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

-x ttymode=raw

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)

CS (aka "force OB hack")

@nnn (hard hibernate)

K (delayed poweroff)

Z (instant poweroff)

SHUTDOWN CONTROL BY NUT¶

There are three options used to control the shutdown behaviour.

sdtype=[0-5]

advorder=no|[0-4]+

awd=[0-9]{1,3}

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.

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

shutdown.return cs

shutdown.return at:<nbr>

shutdown.stayoff

load.off

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:

PREVIOUS DRIVER VERSION¶

Previous driver is still available as apcsmart-old, should there be any need to use earlier version (bugs, incompatibilities with new functionality, etc.). In due time, apcsmart-old will be phased out completely, but this won’t happen until the new version gets solid exposure with no pending issues.

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.

AUTHORS AND HISTORY¶

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), usbhid-ups(8), solis(8)