Imported Upstream version 2.6.2

docs/man/apcsmart.8

@@ -2,12 +2,12 @@
 .\"     Title: apcsmart
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
-.\"      Date: 05/31/2011
+.\"      Date: 09/15/2011
 .\"    Manual: NUT Manual
 .\"    Source: Network UPS Tools
 .\"  Language: English
 .\"
-.TH "APCSMART" "8" "05/31/2011" "Network UPS Tools" "NUT Manual"
+.TH "APCSMART" "8" "09/15/2011" "Network UPS Tools" "NUT Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -33,7 +33,7 @@ apcsmart \- Driver for American Power Conversion Smart Protocol UPS equipment
 .sp
 \fBapcsmart\fR \-h
 .sp
-\fBapcsmart\fR \-a \fIUPS_NAME\fR [\fIOPTIONS\fR]
+\fBapcsmart\fR \-a \*(AqUPS_NAME\*(Aq [\-x option=value \&...]
 .if n \{\
 .sp
 .\}
@@ -52,61 +52,446 @@ This man page only documents the hardware\-specific features of the apcsmart dri
 .RE
 .SH "SUPPORTED HARDWARE"
 .sp
-apcsmart should recognize all recent APC models that use a serial protocol at 2400 bps\&. This is primarily the Smart\-UPS, Matrix\-UPS and Back\-UPS Pro lines\&.
+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
-The driver attempts to support every bell and whistle of the APC reporting interface, whether or not this is strictly sensible\&.
+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
-Some older hardware may only report a handful of variables\&. This is usually not a bug\(emthey just don\(cqt support anything else\&.
+.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 cable= definition described below\&.
+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\-0024C cable is broken or missing, use this diagram to build a clone:
 .sp
 http://www\&.networkupstools\&.org/cables/940\-0024C\&.jpg
-.SH "EXTRA ARGUMENTS"
 .sp
-This driver supports the following optional settings in the \fBups.conf\fR(5):
+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 "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
-\fBcable=940\-0095B\fR
+\fBS\fR (soft hibernate)
 .RS 4
-Configure the serial port for the APC 940\-0095B dual\-mode cable\&.
+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
-\fBsdtype=\fR\fInum\fR
+"new" models
 .RS 4
-Use shutdown type
-\fInum\fR, according to this table:
+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\*(Aqre 3 options used to control 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
-soft shutdown or powerdown, depending on battery status
+issue soft hibernate (\fBS\fR) if the ups is running on batteries, otherwise issue hard hibernate (\fB@\fR)
 .RE
 .PP
 1
 .RS 4
-soft shutdown followed by powerdown
+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
-instant power off
+issue instant poweroff (\fBZ\fR)
 .RE
 .PP
 3
 .RS 4
-power off with grace period
+issue delayed poweroff (\fBK\fR)
 .RE
 .PP
 4
 .RS 4
-"force OB" hack method for CS 350
+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:<nbr>
+.RS 4
+executes "hard hibernate" with <nbr>*6 minutes additional wakeup delay (<nbr> 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
-Modes 0 and 1 will power up the load when power returns\&. Modes 2 and 3 will keep the load turned off when the power returns\&.
+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
-Mode 4 exploits an oddity in the CS 350 models since they only seem to support the S command, but then only when running on battery\&. As a result, the driver will force the UPS to go on battery if necessary before sending the shutdown command\&. This ensures that the load gets reset\&.
+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 "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\&.
@@ -114,11 +499,10 @@ Some older APC UPS models return bogus data in the status register during a fron
 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 <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\&.
+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>
 .SH "SEE ALSO"
-.SS "The core driver:"
 .sp
-\fBnutupsdrv\fR(8)
+\fBnutupsdrv\fR(8), \fBups.conf\fR(5)
 .SS "Internet resources:"
 .sp
 The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/