| blob | dc05d83ede3375f6bdf6aba9f3b1f944231b19d5 |
1 .\" manual page [] for apctest version 3.14.6
2 .Dd January 10, 2009
3 .Dt APCTEST 8
4 .Os apctest v3.14.6
5 .Sh NAME
6 .Nm apctest
7 .Nd apcupsd(8) test program
8 .Sh SYNOPSIS
9 .Nm
10 .Sh DESCRIPTION
11 .Nm
12 is a program that enables the running of certain low-level tests to
13 check the operation of the attached simple signalling American Power
14 Conversion Corp (APC) UPS and to check that your
15 .Xr apcupsd 8
16 configuration is correctly setup and can establish communication with
17 the UPS.
18 .Pp
19 For an APC UPS operating in APC smart protocol mode,
20 .Nm
21 enables the reading and programming of the values of the UPS EEPROM
22 configuration variables as well and the performing of a battery
23 runtime calibration. It also provides a simple TTY chat mode which
24 allows direct interaction with the UPS via the APC smart protocol.
25 For details of this protocol and the available commands, refer to the
26 detailed "APC Smart Protocol" section in the apcupsd manual.
27 .Pp
28 IMPORTANT: Before running
29 .Nm
30 .Pp
31 .Bl -bullet
32 .It
33 Check that the UPSCABLE, UPSTYPE and DEVICE configuration directives in the
34 .Xr apcupsd.conf 5
35 configuration file have been set appropriately; and
36 .It
37 Shutdown apcupsd if it is running. You cannot run both
38 .Xr apcupsd
39 and
40 .Nm
41 at the same time.
42 .El
43 .Pp
44 When run,
45 .Nm
46 displays a menu of options which are different depending on
47 whether the UPS is connected to a USB port or to
48 a serial port. For a serial port connection, there are two
49 different menus depending on whether the UPS is operating in
50 APC smart protocol mode or simple signalling mode - this also depends on
51 which cable is used to connect to the UPS. If a simple signalling
52 cable is used to connect to a Smart-UPS, the UPS will only be able
53 to operate in simple signalling mode.
54 .Pp
55 .Nm
56 saves a transcript of the session to the file
57 .Pa apctest.out
58 in the directory from which the program was called. Its content is
59 useful for debugging purposes.
60 .Sh USB PORT
61 When using a UPS connected to a USB port (eg Back-UPS RS 1500),
62 the following menu options will appear:
63 .Ss Option 1) Test kill UPS power
64 Performs a power down of the UPS into hibernate mode.
65 .Ss Option 2) Perform self-test
66 Performs an immediate self-test (switches to battery power to do so).
67 .Ss Option 3) Read last self-test result
68 Displays the last self-test result.
69 .Ss Option 4) View/Change battery date
70 Displays the current battery replacement date and optionally allows you
71 to change it - useful when the battery
72 is replaced so that you can accurately keep track of its age.
73 .Ss Option 5) View manufacturing date
74 Displays the date the UPS was manufactured.
75 .Ss Option 6) View/Change alarm behavior
76 Sets the delay period before the UPS starts sounding its alarm
77 when the utility power is lost.
78 .Ss Option 7) View/Change sensitivity
79 Changes how sensitive the UPS is to the utility power quality and
80 voltage fluctuations - (H)igh, (M)edium or (L)ow. The higher the
81 sensitivity, the faster the UPS will switch to battery power or
82 activate SmartBoost/SmartTrim (features that avoid using battery power
83 provided the under/over voltage is within 12% of nominal).
84 This setting should normally be set to High unless the UPS switches
85 to battery power frequently, in which case a less sensitive setting
86 will preserve UPS batteries... if the connected equipment can tolerate
87 the power quality.
88 .Ss Option 8) View/Change low transfer voltage
89 Sets the low voltage level at which the UPS switches to battery or
90 activates SmartBoost.
91 .Ss Option 9) View/Change high transfer voltage
92 Sets the high voltage level at which the UPS switches to battery or
93 activates SmartTrim.
94 .Ss Option 10) Perform battery calibration
95 This performs a battery runtime calibration. This can only
96 be performed if your battery is charged to 100% of capacity.
97 The runtime calibration discharges the UPS battery to
98 approximately 25% of capacity. The exact percentage depends on
99 the UPS model.
100 .Pp
101 The advantage of doing this calibration is that the UPS will
102 recalibrate the remaining runtime counter that it maintains
103 and therefore report a more accurate estimated runtime.
104 As batteries age, they tend to hold less charge, so the UPS's
105 internal runtime counter may not be accurate after several
106 years.
107 .Pp
108 It is recommended that battery runtime calibration be performed
109 annually. Performing it too often shortens the lifetime of the
110 UPS batteries.
111 .Ss Option 11) Test Alarm
112 This option will cause the UPS alarm beeper to sound for several seconds.
113 .Ss Option 12) View/Change self-test interval
114 This option allows you to change the time interval between automatic UPS
115 self-tests.
116 .Ss Option Q) Quit
117 Exits from the program.
118 .Sh SERIAL PORT (SMART PROTOCOL MODE)
119 When using a UPS operating in APC smart protocol mode (eg a Smart-UPS)
120 the following menu options will appear:
121 .Ss Option 1) Query the UPS for all known values
122 Selecting this option probes the UPS for all EEPROM configuration
123 variable values known
124 to
125 .Nm
126 and displays them in rather raw format. This output
127 can be useful for providing technical support if you are having
128 problems with the behaviour of the UPS or
129 .Xr apcupsd 8 .
130 .Ss Option 2) Perform a Battery Runtime Calibration
131 This performs a battery runtime calibration. This can only
132 be performed if your battery is charged to 100% of capacity.
133 The runtime calibration discharges the UPS battery to
134 approximately 25% of capacity. The exact percentage depends on
135 the UPS model.
136 .Nm
137 can optionally abort the calibration if it detects that the
138 battery charge is below 10%.
139 .Pp
140 The advantage of doing this calibration is that the UPS will
141 recalibrate the remaining runtime counter that it maintains
142 and therefore report a more accurate estimated runtime.
143 As batteries age, they tend to hold less charge, so the UPS's
144 internal runtime counter may not be accurate after several
145 years.
146 .Pp
147 It is recommended that battery runtime calibration be performed
148 annually. Performing it too often shortens the lifetime of the
149 UPS batteries.
150 .Ss Option 3) Abort Battery Calibration
151 This option aborts an in progress battery runtime calibration.
152 .Pp
153 .Ss Option 4) Monitor Battery Calibration progress
154 Allows restarting of the monitoring of a battery runtime calibration.
155 .Ss Option 5) Program EEPROM
156 Allows the programming of the values of a Smart-UPS's EEPROM
157 configuration variables.
158 .Pp
159 Choosing this option presents a sub-menu of programming
160 options which are detailed below.
161 .Bl -hang
162 .It Option 1) Print EEPROM values
163 .Pp
164 Prints the value of all EEPROM configuration variables known to
165 .Nm .
166 .It Option 2) Change Battery date
167 .Pp
168 Changes the battery date - useful when the battery
169 is replaced so that you can accurately keep track of its age.
170 .It Option 3) Change UPS name
171 .Pp
172 Changes the UPS name - use no more than 8 characters to name the UPS.
173 .It Option 4) Change sensitivity
174 .Pp
175 Changes how sensitive the UPS is to the utility power quality and
176 voltage fluctuations - (H)igh, (M)edium or (L)ow. The higher the
177 sensitivity, the faster the UPS will switch to battery power or
178 activate SmartBoost/SmartTrim (features that avoid using battery power
179 provided the under/over voltage is within 12% of nominal).
180 This setting should normally be set to High unless the UPS switches
181 to battery power frequently, in which case a less sensitive setting
182 will preserve UPS batteries... if the connected equipment can tolerate
183 the power quality.
184 .It Option 5) Change alarm delay
185 .Pp
186 Changes the delay period before the UPS starts sounding its alarm
187 when the utility power is lost.
188 .It Option 6) Change low battery warning delay
189 .Pp
190 Changes the remaining runtime minutes at which the UPS will send the
191 low battery signal. When the UPS internally calculates that the specified
192 number of minutes remains before battery power will be exhausted, it sends
193 the low battery warning.
194 .It Option 7) Change wakeup delay
195 .Pp
196 Changes the delay before the UPS restores power to connected equipment
197 when the utility power returns after shutting down in hibernate mode.
198 .It Option 8) Change shutdown delay
199 .Pp
200 Changes the delay for which the UPS waits before shutting off
201 power to the connected equipment after being commanded to power
202 down in hibernate mode.
203 .It Option 9) Change low transfer voltage
204 .Pp
205 Changes the low voltage level at which the UPS switches to battery or
206 activates SmartBoost.
207 .It Option 10) Change high transfer voltage
208 .Pp
209 Changes the high voltage level at which the UPS switches to battery or
210 activates SmartTrim.
211 .It Option 11) Change battery return threshold percent
212 .Pp
213 Changes the battery charge percentage required after power down in
214 hibernate mode before to the UPS will restore power to connected
215 equipment on the return of utility power.
216 .It Option 12) Change output voltage when on batteries
217 .Pp
218 Changes the nominal voltage output when the UPS is running on battery
219 power.
220 .It Option 13) Change the self test interval
221 .Pp
222 Changes or disables the automatic self-test interval.
223 .It Option 14) Set EEPROM with configuration file values
224 .Pp
225 This option allows the bulk programming of the EEPROM configuration variables
226 from the values contained in the
227 .Pa /etc/apcupsd.conf
228 configuration file. Refer to the "APCTEST EEPROM CONFIGURATION DIRECTIVES"
229 section of the man page for
230 .Xr apcupsd.conf 5
231 .It Option 15) Quit
232 .Pp
233 This option exits back to the previous (main) menu.
234 .El
235 .Ss Option 6) Enter TTY mode communicating with UPS
236 This option allows direct interaction with the attached UPS
237 using the APC smart protocol commands.
238 .Pp
239 WARNING: Take special care what commands you enter because
240 it is possible to cause the UPS to suddenly shutdown or, in the
241 worst case, modify the UPS in such a way as to permanently disable
242 it. Do NOT experiment with unknown or unsupported commands. Caveat
243 Utilitor!
244 .Ss Option 7) Quit
245 Exits from the program.
246 .Sh SERIAL PORT (SIMPLE SIGNALLING MODE)
247 When using an APC UPS operating in simple signalling mode
248 the following menu options will appear:
249 .Ss Option 1) Test 1 - normal mode
250 The test result depends on the model of UPS and type of cable being
251 used. Refer to the "Using apctest on Serial-Line UPSses" section
252 in the apcupsd manual for details.
253 .Ss Option 2) Test 2 - no cable
254 The test result depends on the model of UPS and type of cable being
255 used. Refer to the "Using apctest on Serial-Line UPSses" section
256 in the apcupsd manual for details.
257 .Ss Option 3) Test 3 - no power
258 The test result depends on the model of UPS and type of cable being
259 used. Refer to the "Using apctest on Serial-Line UPSses" section
260 in the apcupsd manual for details.
261 .Ss Option 4) Test 4 - low battery (requires Test 3 first)
262 The test result depends on the model of UPS and type of cable being
263 used. Refer to the "Using apctest on Serial-Line UPSses" section
264 in the apcupsd manual for details.
265 .Ss Option 5) Test 5 - battery exhausted
266 The test result depends on the model of UPS and type of cable being
267 used. Refer to the "Using apctest on Serial-Line UPSses" section
268 in the apcupsd manual for details.
269 .Ss Option 6) Test 6 - kill UPS power
270 The test result depends on the model of UPS and type of cable being
271 used. Refer to the "Using apctest on Serial-Line UPSses" section
272 in the apcupsd manual for details.
273 .Ss Option 7) Test 7 - run tests 1 through 5
274 This option has
275 .Nm
276 guess which cable should be used with the attached UPS.
277 .Ss Option 9) Quit
278 Exits from the program.
279 .Sh FILES
280 .Pa /etc/apcupsd/apcupsd.conf
281 default configuration file
282 .Pp
283 .Pa apctest.out
284 transcript of the
285 .Nm
286 session
287 .Sh SEE ALSO
288 .Xr apcupsd.conf 5 ,
289 .Xr apcupsd 8 .
290 .Pp
291 The HTML apcupsd manual installed on your system or available online at
292 http://www.apcupsd.org/
293 .Sh AUTHORS
294 .Ss This page
295 .An Trevor Roydhouse (current)
296 .An Robert Huff
297 .Ss Software
298 .An Adam Kropelin (current Project Manager and Code Maintainer)
299 .An Kern Sibbald (former Project Manager and Code Maintainer)
300 .An Riccardo Facchetti (former Project Manager and Code Maintainer)
301 .An Andre M. Hedrick (Project Founder and former Code Maintainer)
302 .Ss Contributors
303 An enormous number of users who have devoted their time and energy to
304 this project -- thanks.