apcsmart - Man Page

apcsmart -h

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

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

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:

• Smart-UPS 2000I
• Smart-UPS 900I

"new" models

These models usually come from late 1990s / pre-2009 times​. They are often referred to as "3rd​. gen"​. For the most part, they have programmable EEPROM, report supported commands and capabilities, and should work just fine with the apcsmart driver​.

"microlink" models

WARNING: These are not natively supported by apcsmart (or as of this writing by apcupsd, for that matter, if you’re wondering)​. Around 2007, APC (now APC Schneider) decided to go back to its proprietary 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 a "legacy communications card" —  part #AP9620 (google AP9620 for more details)​. Or if that’s not an option, rely on official software​.

UPDATE:. Later releases of apcupsd claimed support for new APC protocols, so it is worth checking if apcupsd software would work with your device, and apcupsd-ups NUT driver would handle it as part of NUT-managed ecosystem​.

Microsol models

Several Microsol serial models sold in Brazil have been rebranded as APC Back-UPS, and the model numbers tend to start with "BZ"​. If you have one of these "Nobreaks", they will not work with the apcsmart driver — please see the solis(8) driver instead​.

Example models:

• Back-UPS BZ1200-BR
• Back-UPS BZ2200BI-BR

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

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

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

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 the 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​.

There’s a delay between "simulate power failure" and S — by default set to 3​.5s​. You can control it through cshdelay option (allowed values are from 0 to 9​.9)​.

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 wake-up delay (in 6 minute units)​.

"old" models:

The behaviour is — unfortunately — similarly primitive to S​. The UPS unconditionally wakes up after nnn*6 minutes: it doesn’t care if the power returned !

Note
If nnn = 000, then UPS will do precisely nothing​. On those models you should better specify 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​.

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 succeeds​. 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 wake-up 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​.

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

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 wake-up 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:

• load​.on
• test​.panel​.start
• test​.failure​.start
• test​.battery​.start
• test​.battery​.stop
• bypass​.start
• bypass​.stop
• calibrate​.start
• calibrate​.stop

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

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

Nigel Metheringham <Nigel​.Metheringham@Intechnology​.co​.uk> (drawing heavily on the original apcsmart driver by Russell Kroll) wrote a driver called newapc for a time, which was renamed in the 1​.5 series​.

In 2​.6​.2 that driver was renamed finally to apcsmart-old, being superseded by this updated version with new features which currently holds the apcsmart name, and is maintained by Michal Soltys <soltys@ziu​.info>​.

nutupsdrv(8), ups.conf(5), usbhid-ups(8), solis(8)

nut(7), nutupsdrv(8), upscmd(8), ups.conf(5), upsd(8), upsset.cgi(8).