1APCTEST(8)                BSD System Manager's Manual               APCTEST(8)
2

NAME

4     apctest apcupsd(8) test program
5

SYNOPSIS

7     apctest
8

DESCRIPTION

10     apctest is a program that enables the running of certain low-level tests
11     to check the operation of the attached simple signalling American Power
12     Conversion Corp (APC) UPS and to check that your apcupsd(8) configuration
13     is correctly setup and can establish communication with the UPS.
14
15     For an APC UPS operating in APC smart protocol mode, apctest enables the
16     reading and programming of the values of the UPS EEPROM configuration
17     variables as well and the performing of a battery runtime calibration. It
18     also  provides a simple TTY chat mode which allows direct interaction
19     with the UPS via the APC smart protocol.  For details of this protocol
20     and the available commands, refer to the detailed "APC Smart Protocol"
21     section in the apcupsd manual.
22
23     IMPORTANT: Before running apctest
24
25     ·   Check that the UPSCABLE, UPSTYPE and DEVICE configuration directives
26         in the apcupsd.conf(5) configuration file have been set appropri‐
27         ately; and
28
29     ·   Shutdown apcupsd if it is running. You cannot run both apcupsd and
30         apctest at the same time.
31
32     When run, apctest displays a menu of options which are different depend‐
33     ing on whether the UPS is connected to a USB port or to a serial port.
34     For a serial port connection, there are two different menus depending on
35     whether the UPS is operating in APC smart protocol mode or simple sig‐
36     nalling mode - this also depends on which cable is used to connect to the
37     UPS. If a simple signalling cable is used to connect to a Smart-UPS, the
38     UPS will only be able to operate in simple signalling mode.
39
40     apctest saves a transcript of the session to the file apctest.out in the
41     directory from which the program was called. Its content is useful for
42     debugging purposes.
43

USB PORT

45     When using a UPS connected to a USB port (eg Back-UPS RS 1500), the fol‐
46     lowing menu options will appear:
47
48   Option 1) Test kill UPS power
49     Performs a power down of the UPS into hibernate mode.
50
51   Option 2) Perform self-test
52     Performs an immediate self-test (switches to battery power to do so).
53
54   Option 3) Read last self-test result
55     Displays the last self-test result.
56
57   Option 4) View/Change battery date
58     Displays the current battery replacement date and optionally allows you
59     to change it - useful when the battery is replaced so that you can accu‐
60     rately keep track of its age.
61
62   Option 5) View manufacturing date
63     Displays the date the UPS was manufactured.
64
65   Option 6) View/Change alarm behavior
66     Sets the delay period before the UPS starts sounding its alarm when the
67     utility power is lost.
68
69   Option 7) View/Change sensitivity
70     Changes how sensitive the UPS is to the utility power quality and voltage
71     fluctuations - (H)igh, (M)edium or (L)ow. The higher the sensitivity, the
72     faster the UPS will switch to battery power or activate SmartBoost/Smart‐
73     Trim (features that avoid using battery power provided the under/over
74     voltage is within 12% of nominal).  This setting should normally be set
75     to High unless the UPS switches to battery power frequently, in which
76     case a less sensitive setting will preserve UPS batteries... if the con‐
77     nected equipment can tolerate the power quality.
78
79   Option 8) View/Change low transfer voltage
80     Sets the low voltage level at which the UPS switches to battery or acti‐
81     vates SmartBoost.
82
83   Option 9) View/Change high transfer voltage
84     Sets the high voltage level at which the UPS switches to battery or acti‐
85     vates SmartTrim.
86
87   Option 10) Perform battery calibration
88     This performs a battery runtime calibration. This can only be performed
89     if your battery is charged to 100% of capacity.  The runtime calibration
90     discharges the UPS battery to approximately 25% of capacity. The exact
91     percentage depends on the UPS model.
92
93     The advantage of doing this calibration is that the UPS will recalibrate
94     the remaining runtime counter that it maintains and therefore report a
95     more accurate estimated runtime.  As batteries age, they tend to hold
96     less charge, so the UPS's internal runtime counter may not be accurate
97     after several years.
98
99     It is recommended that battery runtime calibration be performed annually.
100     Performing it too often shortens the lifetime of the UPS batteries.
101
102   Option 11) Test Alarm
103     This option will cause the UPS alarm beeper to sound for several seconds.
104
105   Option 12) View/Change self-test interval
106     This option allows you to change the time interval between automatic UPS
107     self-tests.
108
109   Option Q) Quit
110     Exits from the program.
111

SERIAL PORT (SMART PROTOCOL MODE)

113     When using a UPS operating in APC smart protocol mode (eg a Smart-UPS)
114     the following menu options will appear:
115
116   Option 1) Query the UPS for all known values
117     Selecting this option probes the UPS for all EEPROM configuration vari‐
118     able values known to apctest and displays them in rather raw format. This
119     output can be useful for providing technical support if you are having
120     problems with the behaviour of the UPS or apcupsd(8).
121
122   Option 2) Perform a Battery Runtime Calibration
123     This performs a battery runtime calibration. This can only be performed
124     if your battery is charged to 100% of capacity.  The runtime calibration
125     discharges the UPS battery to approximately 25% of capacity. The exact
126     percentage depends on the UPS model.  apctest can optionally abort the
127     calibration if it detects that the battery charge is below 10%.
128
129     The advantage of doing this calibration is that the UPS will recalibrate
130     the remaining runtime counter that it maintains and therefore report a
131     more accurate estimated runtime.  As batteries age, they tend to hold
132     less charge, so the UPS's internal runtime counter may not be accurate
133     after several years.
134
135     It is recommended that battery runtime calibration be performed annually.
136     Performing it too often shortens the lifetime of the UPS batteries.
137
138   Option 3) Abort Battery Calibration
139     This option aborts an in progress battery runtime calibration.
140
141   Option 4) Monitor Battery Calibration progress
142     Allows restarting of the monitoring of a battery runtime calibration.
143
144   Option 5) Program EEPROM
145     Allows the programming of the values of a Smart-UPS's EEPROM configura‐
146     tion variables.
147
148     Choosing this option presents a sub-menu of programming options which are
149     detailed below.
150
151     Option 1) Print EEPROM values
152
153             Prints the value of all EEPROM configuration variables known to
154             apctest.
155
156     Option 2) Change Battery date
157
158             Changes the battery date - useful when the battery is replaced so
159             that you can accurately keep track of its age.
160
161     Option 3) Change UPS name
162
163             Changes the UPS name - use no more than 8 characters to name the
164             UPS.
165
166     Option 4) Change sensitivity
167
168             Changes how sensitive the UPS is to the utility power quality and
169             voltage fluctuations - (H)igh, (M)edium or (L)ow. The higher the
170             sensitivity, the faster the UPS will switch to battery power or
171             activate SmartBoost/SmartTrim (features that avoid using battery
172             power provided the under/over voltage is within 12% of nominal).
173             This setting should normally be set to High unless the UPS
174             switches to battery power frequently, in which case a less sensi‐
175             tive setting will preserve UPS batteries... if the connected
176             equipment can tolerate the power quality.
177
178     Option 5) Change alarm delay
179
180             Changes the delay period before the UPS starts sounding its alarm
181             when the utility power is lost.
182
183     Option 6) Change low battery warning delay
184
185             Changes the remaining runtime minutes at which the UPS will send
186             the low battery signal. When the UPS internally calculates that
187             the specified number of minutes remains before battery power will
188             be exhausted, it sends the low battery warning.
189
190     Option 7) Change wakeup delay
191
192             Changes the delay before the UPS restores power to connected
193             equipment when the utility power returns after shutting down in
194             hibernate mode.
195
196     Option 8) Change shutdown delay
197
198             Changes the delay for which the UPS waits before shutting off
199             power to the connected equipment after being commanded to power
200             down in hibernate mode.
201
202     Option 9) Change low transfer voltage
203
204             Changes the low voltage level at which the UPS switches to bat‐
205             tery or activates SmartBoost.
206
207     Option 10) Change high transfer voltage
208
209             Changes the high voltage level at which the UPS switches to bat‐
210             tery or activates SmartTrim.
211
212     Option 11) Change battery return threshold percent
213
214             Changes the battery charge percentage required after power down
215             in hibernate mode before to the UPS will restore power to con‐
216             nected equipment on the return of utility power.
217
218     Option 12) Change output voltage when on batteries
219
220             Changes the nominal voltage output when the UPS is running on
221             battery power.
222
223     Option 13) Change the self test interval
224
225             Changes or disables the automatic self-test interval.
226
227     Option 14) Set EEPROM with configuration file values
228
229             This option allows the bulk programming of the EEPROM configura‐
230             tion variables from the values contained in the /etc/apcupsd.conf
231             configuration file.  Refer to the "APCTEST EEPROM CONFIGURATION
232             DIRECTIVES" section of the man page for apcupsd.conf(5)
233
234     Option 15) Quit
235
236             This option exits back to the previous (main) menu.
237
238   Option 6) Enter TTY mode communicating with UPS
239     This option allows direct interaction with the attached UPS using the APC
240     smart protocol commands.
241
242     WARNING: Take special care what commands you enter because it is possible
243     to cause the UPS to suddenly shutdown or, in the worst case, modify the
244     UPS in such a way as to permanently disable it. Do NOT experiment with
245     unknown or unsupported commands. Caveat Utilitor!
246
247   Option 7) Quit
248     Exits from the program.
249

SERIAL PORT (SIMPLE SIGNALLING MODE)

251     When using an APC UPS operating in simple signalling mode the following
252     menu options will appear:
253
254   Option 1) Test 1 - normal mode
255     The test result depends on the model of UPS and type of cable being used.
256     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
257     manual for details.
258
259   Option 2) Test 2 - no cable
260     The test result depends on the model of UPS and type of cable being used.
261     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
262     manual for details.
263
264   Option 3) Test 3 - no power
265     The test result depends on the model of UPS and type of cable being used.
266     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
267     manual for details.
268
269   Option 4) Test 4 - low battery (requires Test 3 first)
270     The test result depends on the model of UPS and type of cable being used.
271     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
272     manual for details.
273
274   Option 5) Test 5 - battery exhausted
275     The test result depends on the model of UPS and type of cable being used.
276     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
277     manual for details.
278
279   Option 6) Test 6 - kill UPS power
280     The test result depends on the model of UPS and type of cable being used.
281     Refer to the "Using apctest on Serial-Line UPSses" section in the apcupsd
282     manual for details.
283
284   Option 7) Test 7 - run tests 1 through 5
285     This option has apctest guess which cable should be used with the
286     attached UPS.
287
288   Option 9) Quit
289     Exits from the program.
290

FILES

292     /etc/apcupsd/apcupsd.conf default configuration file
293
294     apctest.out transcript of the apctest session
295

SEE ALSO

297     apcupsd.conf(5), apcupsd(8).
298
299     The HTML apcupsd manual installed on your system or available online at
300     http://www.apcupsd.org/
301

AUTHORS

303   This page
304     Trevor Roydhouse (current)
305     Robert Huff
306
307   Software
308     Adam Kropelin (current Project Manager and Code Maintainer)
309     Kern Sibbald (former Project Manager and Code Maintainer)
310     Riccardo Facchetti (former Project Manager and Code Maintainer)
311     Andre M. Hedrick (Project Founder and former Code Maintainer)
312
313   Contributors
314     An enormous number of users who have devoted their time and energy to
315     this project -- thanks.
316
317apctest v3.14.6                January 10, 2009                apctest v3.14.6
Impressum