'\" t .\" Title: apcsmart .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 02/25/2014 .\" Manual: NUT Manual .\" Source: Network UPS Tools 2.7.1.5 .\" Language: English .\" .TH "APCSMART" "8" "02/25/2014" "Network UPS Tools 2\&.7\&.1\&." "NUT Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" apcsmart \- Driver for American Power Conversion Smart Protocol UPS equipment .SH "SYNOPSIS" .sp \fBapcsmart\fR \-h .sp \fBapcsmart\fR \-a \*(AqUPS_NAME\*(Aq [\-x option=value \&...] .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp This man page only documents the hardware\-specific features of the apcsmart driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&. .sp .5v .RE .SH "SUPPORTED HARDWARE" .sp 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\&. .sp Currently we can roughly divide APC hardware into 3 groups (note that the division isn\*(Aqt strict by any means, and the borders between those are pretty fuzzy): .PP [very] "old" models .RS 4 These models usually have old APC logo, white color and \fIno\fR programmable eeprom; You won\*(Aqt find them listed anywhere on APC\(cqs site either\&. The support for those will be usually based on driver\*(Aqs 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)\&. .PP \fBExample models:\fR .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Smart\-UPS 2000I .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Smart\-UPS 900I .RE .RE .PP "new" models .RS 4 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\&. .RE .PP "microlink" models .RS 4 WARNING: these are not \fInatively\fR supported by apcsmart (or apcupsd for that matter, if you\(cqre 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 \fBNUT\fR is to purchase "legacy communications card" \- part #AP9620 (google \*(AqAP9620\*(Aq for more details)\&. Or if that\*(Aqs not an option, rely on official software\&. .RE .sp 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\&. .SH "CABLING" .sp 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 \*(Aqcable=\*(Aq definition described below\&. .sp If your 940\-xx24X cable is broken or missing, use this diagram to build a clone: .sp http://www\&.networkupstools\&.org/cables\&.html#_940_0024c_clone .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp 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\&. .sp .5v .RE .sp You can specify alternate cable in \fBups.conf\fR(5): .sp \fBcable\fR=940\-0095B .sp Alternatively, you can also provide it on the command line using: .sp \-x \fBcable\fR=940\-0095B .SH "TTY MODES" .sp By default the driver works in canonical mode, but it showed to be a problem in windows systems\&. Furthermore there\(cqs a possibility of some obscure serial cards or serial\-usb convertes that could cause problems as well\&. You can use \*(Aqttymode=\*(Aq option to force non\-canonical discipline in \fBups.conf\fR(5): .sp \fBttymode\fR=raw .sp Alternatively, you can also provide it on the command line using: .sp \-x \fBttymode\fR=raw .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp Any other value will make the driver work in the canonical mode\&. .sp .5v .RE .SH "EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES" .sp APC hardware supports a lot of shutdown methods, that themselves can differ in behaviour quite a bit, depending on the model\&. .PP \fBS\fR (soft hibernate) .RS 4 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\&. \fBThe command doesn\*(Aqt work if UPS is running on mains\&.\fR .PP "old" models .RS 4 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\&. .RE .PP "new" models .RS 4 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\*(Aqs return\&. .RE .RE .PP \fBCS\fR (aka "force OB hack") .RS 4 This is a trick to make UPS power down even if it\*(Aqs running on mains\&. Immediately before issuing \fBS\fR, "simulate power failure" is issued\&. The remaining behaviour is as in \fBS\fR case\&. .sp The name came from APC CS models, where such trick was used to power down UPSes in consistent fashion using only \fBS\fR\&. It\*(Aqs better to use \fB@nnn\fR command if your UPS supports it (and is not too old, see below)\&. .RE .PP \fB@nnn\fR (hard hibernate) .RS 4 This is basic command used to hibernate UPS regardless if it\*(Aqs 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)\&. .PP "old" models .RS 4 The behaviour is \- unfortunately \- similary primitive to \fBS\fR\&. The UPS unconditionally wakes up after nnn*6 minutes \- \fBit doesn\*(Aqt care if the power returned !\fR If nnn = 000, then UPS will do precisely nothing\&. On those models you\*(Aqre 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 \fBS\fR, the serial connection is kept alive)\&. .RE .PP "new" models .RS 4 All the usual variables defined in eeprom are respected (see \fBS\fR)\&. Additionally, if nnn > 0, the nnn*6 minutes are added to eeprom defined delay\&. UPS will not power up if it\*(Aqs running on batteries, contrary to what "old" models used to do \- the combined delay is counted from the moment of power return\&. .RE .sp 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 (\fBawd\fR option, or argument to one of the supported instant commands)\&. .RE .PP \fBK\fR (delayed poweroff) .RS 4 This is permanent poweroff \- the UPS will not wake up automatically\&. On newer units, it will respect applicable eeprom variables\&. .RE .PP \fBZ\fR (instant poweroff) .RS 4 This is also permanent poweroff \- the UPS will not wake up automatically\&. The poweroff is executed immediately\&. .RE .SH "SHUTDOWN CONTROL BY NUT" .sp There are three options used to control the shutdown behaviour\&. .PP \fBsdtype\fR=[0\-5] .RS 4 This option takes a single digit (0\-5) as an argument\&. See below for details\&. .RE .PP \fBadvorder\fR=no|[0\-4]+ .RS 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 \fBsdtype\fR\&. See below for details\&. .RE .PP \fBawd\fR=[0\-9]{1,3} .RS 4 This option lets you specify additional wakeup delay used by \fB@\fR\&. 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\&. \fBNote: the time unit is 6 minutes !\fR .RE .sp Keep in mind that \fBsdtype\fR and \fBadvorder\fR are mutually exclusive\&. If \fBadvorder\fR is provided, \fBsdtype\fR is ignored\&. If \fBadvorder\fR is set to \*(Aqno\*(Aq, \fBsdtype\fR is used instead\&. .sp If nothing is provided, \fBNUT\fR will assume \fBsdtype\fR=0 \- which is generally fine for anything not too ancient or not too quirky\&. .SS "SDTYPE" .sp The values permitted are from 0 to 5\&. Only one can be specified\&. Anything else will cause apcsmart to exit\&. .PP 0 .RS 4 issue soft hibernate (\fBS\fR) if the UPS is running on batteries, otherwise issue hard hibernate (\fB@\fR) .RE .PP 1 .RS 4 issue soft hibernate (\fBS\fR) (if on batteries), and if it fails (or on mains) \- try hard hibernate (\fB@\fR) .RE .PP 2 .RS 4 issue instant poweroff (\fBZ\fR) .RE .PP 3 .RS 4 issue delayed poweroff (\fBK\fR) .RE .PP 4 .RS 4 issue "force OB hack" (\fBCS\fR) .RE .PP 5 .RS 4 issue hard hibernate (\fB@\fR) .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp Hard hibernate\*(Aqs additional wakeup delay can be provided by \fBawd\fR\&. .sp .5v .RE .SS "ADVORDER" .sp The argument is either a word \*(Aqno\*(Aq, 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\&. .sp If \fBadvorder\fR is undefined or set to \*(Aqno\*(Aq, \fBsdtype\fR is used instead\&. .sp The mapping is as follows: .TS tab(:); lt lt lt lt lt lt lt lt lt lt. T{ .sp 0 T}:T{ .sp soft hibernate (\fBS\fR) T} T{ .sp 1 T}:T{ .sp hard hibernate (\fB@\fR) T} T{ .sp 2 T}:T{ .sp delayed poweroff (\fBK\fR) T} T{ .sp 3 T}:T{ .sp instant poweroff (\fBZ\fR) T} T{ .sp 4 T}:T{ .sp "force OB hack" (\fBCS\fR) T} .TE .sp 1 .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp Hard hibernate\*(Aqs additional wakeup delay can be provided by \fBawd\fR\&. .sp .5v .RE .SH "IGNORING LB STATE" .sp 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 \fBignorelb\fR option in driver\*(Aqs section of \fBups.conf\fR(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 \fIonly\fR on two conditions: .sp battery\&.charge < battery\&.charge\&.low .sp \fBOR\fR .sp battery\&.runtime < battery\&.runtime\&.low .sp 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)\&. .sp APC UPSes don\*(Aqt have battery\&.charge\&.low \- you will have to define it if you want to use such condition (prefix the variable with override\&. or default\&.)\&. .sp "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 \fBNUT\fR to initiate the shutdown\&. You might want to disable this condition entirely, when relying on \fBignorelb\fR option (this was actually the main motivation behind introduction of such feature)\&. .sp Simple example: .sp .if n \{\ .RS 4 .\} .nf [apc] ignorelb override\&.battery\&.charge\&.low = 15 override\&.battery\&.runtime\&.low = \-1 .fi .if n \{\ .RE .\} .sp This would cause apcsmart to go into shutdown \fIonly\fR if detected battery charge < 15%\&. Runtime condition is always false in this example\&. .sp 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)\&. \fBignorelb\fR option and \fBoverride\&.*\fR let you remain in control of the UPS, not UPS in control of you\&. .sp Furthermore, this allows to specify conditions similary to how it\(cqs done in apcupsd daemon, so it should be welcome by people used to that software\&. .SH "SUPPORTED INSTANT COMMANDS" .sp The apcsmart driver exposes following instant commands: .PP shutdown\&.return .RS 4 executes soft hibernate .RE .PP shutdown\&.return cs .RS 4 executes "force OB hack" .RE .PP shutdown\&.return at: .RS 4 executes "hard hibernate" with *6 minutes additional wakeup delay ( format is the same as of \fBawd\fR option) .RE .PP shutdown\&.stayoff .RS 4 executes "delayed poweroff" .RE .PP load\&.off .RS 4 executes "instant poweroff" .RE .sp 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\*(Aqre testing\&. .sp Other supported commands: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} load\&.on .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} test\&.panel\&.start .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} test\&.failure\&.start .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} test\&.battery\&.start .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} test\&.battery\&.stop .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} bypass\&.start .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} bypass\&.stop .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} calibrate\&.start .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} calibrate\&.stop .RE .SH "PREVIOUS DRIVER VERSION" .sp Previous driver is still available as apcsmart\-old \- should there be any need to use earlier version (bugs, incompatiblities with new functionality, etc\&.)\&. In due time apcsmart\-old will be phased out completely, but this won\(cqt happen until the new version gets solid exposure with no pending issues\&. .SH "BUGS" .sp 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\&. .sp APC UPS models with both USB and serial ports require a power cycle when switching from USB communication to serial, and perhaps vice versa\&. .SH "AUTHOR" .sp Nigel Metheringham (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 .SH "SEE ALSO" .sp \fBnutupsdrv\fR(8), \fBups.conf\fR(5) .SS "Internet resources:" .sp The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/