1APCTEST(8) BSD System Manager's Manual APCTEST(8)
2
4 apctest — apcupsd(8) test program
5
7 apctest
8
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 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 IMPORTANT: Before running apctest
24 · 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 · Shutdown apcupsd if it is running. You cannot run both apcupsd and
30 apctest at the same time.
31 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 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
45 When using a UPS connected to a USB port (eg Back-UPS RS 1500), the fol‐
46 lowing menu options will appear:
47 Option 1) Test kill UPS power
49 Performs a power down of the UPS into hibernate mode.
50 Option 2) Perform self-test
52 Performs an immediate self-test (switches to battery power to do so).
53 Option 3) Read last self-test result
55 Displays the last self-test result.
56 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 Option 5) View manufacturing date
63 Displays the date the UPS was manufactured.
64 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 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 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 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 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 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 It is recommended that battery runtime calibration be performed annually.
100 Performing it too often shortens the lifetime of the UPS batteries.
101 Option 11) Test Alarm
103 This option will cause the UPS alarm beeper to sound for several seconds.
104 Option 12) View/Change self-test interval
106 This option allows you to change the time interval between automatic UPS
107 self-tests.
108 Option Q) Quit
110 Exits from the program.
111
113 When using a UPS operating in APC smart protocol mode (eg a Smart-UPS)
114 the following menu options will appear:
115 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 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 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 It is recommended that battery runtime calibration be performed annually.
136 Performing it too often shortens the lifetime of the UPS batteries.
137 Option 3) Abort Battery Calibration
139 This option aborts an in progress battery runtime calibration.
140 Option 4) Monitor Battery Calibration progress
142 Allows restarting of the monitoring of a battery runtime calibration.
143 Option 5) Program EEPROM
145 Allows the programming of the values of a Smart-UPS's EEPROM configura‐
146 tion variables.
147 Choosing this option presents a sub-menu of programming options which are
149 detailed below.
150 Option 1) Print EEPROM values
152 Prints the value of all EEPROM configuration variables known to
154 apctest.
155 Option 2) Change Battery date
157 Changes the battery date - useful when the battery is replaced so
159 that you can accurately keep track of its age.
160 Option 3) Change UPS name
162 Changes the UPS name - use no more than 8 characters to name the
164 UPS.
165 Option 4) Change sensitivity
167 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 Option 5) Change alarm delay
179 Changes the delay period before the UPS starts sounding its alarm
181 when the utility power is lost.
182 Option 6) Change low battery warning delay
184 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 Option 7) Change wakeup delay
191 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 Option 8) Change shutdown delay
197 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 Option 9) Change low transfer voltage
203 Changes the low voltage level at which the UPS switches to bat‐
205 tery or activates SmartBoost.
206 Option 10) Change high transfer voltage
208 Changes the high voltage level at which the UPS switches to bat‐
210 tery or activates SmartTrim.
211 Option 11) Change battery return threshold percent
213 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 Option 12) Change output voltage when on batteries
219 Changes the nominal voltage output when the UPS is running on
221 battery power.
222 Option 13) Change the self test interval
224 Changes or disables the automatic self-test interval.
226 Option 14) Set EEPROM with configuration file values
228 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 Option 15) Quit
235 This option exits back to the previous (main) menu.
237 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 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 Option 7) Quit
248 Exits from the program.
249
251 When using an APC UPS operating in simple signalling mode the following
252 menu options will appear:
253 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 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 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 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 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 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 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 Option 9) Quit
289 Exits from the program.
290
292 /etc/apcupsd/apcupsd.conf default configuration file
293 apctest.out transcript of the apctest session
295
297 apcupsd.conf(5), apcupsd(8).
298 The HTML apcupsd manual installed on your system or available online at
300 http://www.apcupsd.org/
301
303 This page
304 Trevor Roydhouse (current)
305 Robert Huff
306 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 Contributors
314 An enormous number of users who have devoted their time and energy to
315 this project -- thanks.
316apctest v3.14.6 January 10, 2009 apctest v3.14.6