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
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
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
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
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
292 /etc/apcupsd/apcupsd.conf default configuration file
293
294 apctest.out transcript of the apctest session
295
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
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