APCTEST
Section: Maintenance Commands (8)
Index
Return to Main Contents
BSD mandoc
apctest v3.14.6
NAME
apctest
- apcupsd(8) test program
SYNOPSIS
apctest
DESCRIPTION
apctest
is a program that enables the running of certain low-level tests to
check the operation of the attached simple signalling American Power
Conversion Corp (APC) UPS and to check that your
apcupsd(8)
configuration is correctly setup and can establish communication with
the UPS.
For an APC UPS operating in APC smart protocol mode,
apctest
enables the reading and programming of the values of the UPS EEPROM
configuration variables as well and the performing of a battery
runtime calibration. It also provides a simple TTY chat mode which
allows direct interaction with the UPS via the APC smart protocol.
For details of this protocol and the available commands, refer to the
detailed "APC Smart Protocol" section in the apcupsd manual.
IMPORTANT: Before running
apctest
-
Check that the UPSCABLE, UPSTYPE and DEVICE configuration directives in the
apcupsd.conf5
configuration file have been set appropriately; and
-
Shutdown apcupsd if it is running. You cannot run both
apcupsd
and
apctest
at the same time.
When run,
apctest
displays a menu of options which are different depending on
whether the UPS is connected to a USB port or to
a serial port. For a serial port connection, there are two
different menus depending on whether the UPS is operating in
APC smart protocol mode or simple signalling mode - this also depends on
which cable is used to connect to the UPS. If a simple signalling
cable is used to connect to a Smart-UPS, the UPS will only be able
to operate in simple signalling mode.
apctest
saves a transcript of the session to the file
apctest.out
in the directory from which the program was called. Its content is
useful for debugging purposes.
USB PORT
When using a UPS connected to a USB port (eg Back-UPS RS 1500),
the following menu options will appear:
Option 1) Test kill UPS power
Performs a power down of the UPS into hibernate mode.
Option 2) Perform self-test
Performs an immediate self-test (switches to battery power to do so).
Option 3) Read last self-test result
Displays the last self-test result.
Option 4) View/Change battery date
Displays the current battery replacement date and optionally allows you
to change it - useful when the battery
is replaced so that you can accurately keep track of its age.
Option 5) View manufacturing date
Displays the date the UPS was manufactured.
Option 6) View/Change alarm behavior
Sets the delay period before the UPS starts sounding its alarm
when the utility power is lost.
Option 7) View/Change sensitivity
Changes how sensitive the UPS is to the utility power quality and
voltage fluctuations - (H)igh, (M)edium or (L)ow. The higher the
sensitivity, the faster the UPS will switch to battery power or
activate SmartBoost/SmartTrim (features that avoid using battery power
provided the under/over voltage is within 12% of nominal).
This setting should normally be set to High unless the UPS switches
to battery power frequently, in which case a less sensitive setting
will preserve UPS batteries... if the connected equipment can tolerate
the power quality.
Option 8) View/Change low transfer voltage
Sets the low voltage level at which the UPS switches to battery or
activates SmartBoost.
Option 9) View/Change high transfer voltage
Sets the high voltage level at which the UPS switches to battery or
activates SmartTrim.
Option 10) Perform battery calibration
This performs a battery runtime calibration. This can only
be performed if your battery is charged to 100% of capacity.
The runtime calibration discharges the UPS battery to
approximately 25% of capacity. The exact percentage depends on
the UPS model.
The advantage of doing this calibration is that the UPS will
recalibrate the remaining runtime counter that it maintains
and therefore report a more accurate estimated runtime.
As batteries age, they tend to hold less charge, so the UPS's
internal runtime counter may not be accurate after several
years.
It is recommended that battery runtime calibration be performed
annually. Performing it too often shortens the lifetime of the
UPS batteries.
Option 11) Test Alarm
This option will cause the UPS alarm beeper to sound for several seconds.
Option 12) View/Change self-test interval
This option allows you to change the time interval between automatic UPS
self-tests.
Option Q) Quit
Exits from the program.
SERIAL PORT (SMART PROTOCOL MODE)
When using a UPS operating in APC smart protocol mode (eg a Smart-UPS)
the following menu options will appear:
Option 1) Query the UPS for all known values
Selecting this option probes the UPS for all EEPROM configuration
variable values known
to
apctest
and displays them in rather raw format. This output
can be useful for providing technical support if you are having
problems with the behaviour of the UPS or
apcupsd(8).
Option 2) Perform a Battery Runtime Calibration
This performs a battery runtime calibration. This can only
be performed if your battery is charged to 100% of capacity.
The runtime calibration discharges the UPS battery to
approximately 25% of capacity. The exact percentage depends on
the UPS model.
apctest
can optionally abort the calibration if it detects that the
battery charge is below 10%.
The advantage of doing this calibration is that the UPS will
recalibrate the remaining runtime counter that it maintains
and therefore report a more accurate estimated runtime.
As batteries age, they tend to hold less charge, so the UPS's
internal runtime counter may not be accurate after several
years.
It is recommended that battery runtime calibration be performed
annually. Performing it too often shortens the lifetime of the
UPS batteries.
Option 3) Abort Battery Calibration
This option aborts an in progress battery runtime calibration.
Option 4) Monitor Battery Calibration progress
Allows restarting of the monitoring of a battery runtime calibration.
Option 5) Program EEPROM
Allows the programming of the values of a Smart-UPS's EEPROM
configuration variables.
Choosing this option presents a sub-menu of programming
options which are detailed below.
- Option 1) Print EEPROM values
-
Prints the value of all EEPROM configuration variables known to
apctest.
- Option 2) Change Battery date
-
Changes the battery date - useful when the battery
is replaced so that you can accurately keep track of its age.
- Option 3) Change UPS name
-
Changes the UPS name - use no more than 8 characters to name the UPS.
- Option 4) Change sensitivity
-
Changes how sensitive the UPS is to the utility power quality and
voltage fluctuations - (H)igh, (M)edium or (L)ow. The higher the
sensitivity, the faster the UPS will switch to battery power or
activate SmartBoost/SmartTrim (features that avoid using battery power
provided the under/over voltage is within 12% of nominal).
This setting should normally be set to High unless the UPS switches
to battery power frequently, in which case a less sensitive setting
will preserve UPS batteries... if the connected equipment can tolerate
the power quality.
- Option 5) Change alarm delay
-
Changes the delay period before the UPS starts sounding its alarm
when the utility power is lost.
- Option 6) Change low battery warning delay
-
Changes the remaining runtime minutes at which the UPS will send the
low battery signal. When the UPS internally calculates that the specified
number of minutes remains before battery power will be exhausted, it sends
the low battery warning.
- Option 7) Change wakeup delay
-
Changes the delay before the UPS restores power to connected equipment
when the utility power returns after shutting down in hibernate mode.
- Option 8) Change shutdown delay
-
Changes the delay for which the UPS waits before shutting off
power to the connected equipment after being commanded to power
down in hibernate mode.
- Option 9) Change low transfer voltage
-
Changes the low voltage level at which the UPS switches to battery or
activates SmartBoost.
- Option 10) Change high transfer voltage
-
Changes the high voltage level at which the UPS switches to battery or
activates SmartTrim.
- Option 11) Change battery return threshold percent
-
Changes the battery charge percentage required after power down in
hibernate mode before to the UPS will restore power to connected
equipment on the return of utility power.
- Option 12) Change output voltage when on batteries
-
Changes the nominal voltage output when the UPS is running on battery
power.
- Option 13) Change the self test interval
-
Changes or disables the automatic self-test interval.
- Option 14) Set EEPROM with configuration file values
-
This option allows the bulk programming of the EEPROM configuration variables
from the values contained in the
/etc/apcupsd.conf
configuration file. Refer to the "APCTEST EEPROM CONFIGURATION DIRECTIVES"
section of the man page for
apcupsd.conf5
- Option 15) Quit
-
This option exits back to the previous (main) menu.
Option 6) Enter TTY mode communicating with UPS
This option allows direct interaction with the attached UPS
using the APC smart protocol commands.
WARNING: Take special care what commands you enter because
it is possible to cause the UPS to suddenly shutdown or, in the
worst case, modify the UPS in such a way as to permanently disable
it. Do NOT experiment with unknown or unsupported commands. Caveat
Utilitor!
Option 7) Quit
Exits from the program.
SERIAL PORT (SIMPLE SIGNALLING MODE)
When using an APC UPS operating in simple signalling mode
the following menu options will appear:
Option 1) Test 1 - normal mode
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 2) Test 2 - no cable
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 3) Test 3 - no power
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 4) Test 4 - low battery (requires Test 3 first)
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 5) Test 5 - battery exhausted
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 6) Test 6 - kill UPS power
The test result depends on the model of UPS and type of cable being
used. Refer to the "Using apctest on Serial-Line UPSses" section
in the apcupsd manual for details.
Option 7) Test 7 - run tests 1 through 5
This option has
apctest
guess which cable should be used with the attached UPS.
Option 9) Quit
Exits from the program.
FILES
/etc/apcupsd/apcupsd.conf
default configuration file
apctest.out
transcript of the
apctest
session
SEE ALSO
apcupsd.conf5,
apcupsd(8).
The HTML apcupsd manual installed on your system or available online at
http://www.apcupsd.org/
AUTHORS
This page
An Trevor Roydhouse (current)
An Robert Huff
Software
An Adam Kropelin (current Project Manager and Code Maintainer)
An Kern Sibbald (former Project Manager and Code Maintainer)
An Riccardo Facchetti (former Project Manager and Code Maintainer)
An Andre M. Hedrick (Project Founder and former Code Maintainer)
Contributors
An enormous number of users who have devoted their time and energy to
this project -- thanks.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- USB PORT
-
- Option 1) Test kill UPS power
-
- Option 2) Perform self-test
-
- Option 3) Read last self-test result
-
- Option 4) View/Change battery date
-
- Option 5) View manufacturing date
-
- Option 6) View/Change alarm behavior
-
- Option 7) View/Change sensitivity
-
- Option 8) View/Change low transfer voltage
-
- Option 9) View/Change high transfer voltage
-
- Option 10) Perform battery calibration
-
- Option 11) Test Alarm
-
- Option 12) View/Change self-test interval
-
- Option Q) Quit
-
- SERIAL PORT (SMART PROTOCOL MODE)
-
- Option 1) Query the UPS for all known values
-
- Option 2) Perform a Battery Runtime Calibration
-
- Option 3) Abort Battery Calibration
-
- Option 4) Monitor Battery Calibration progress
-
- Option 5) Program EEPROM
-
- Option 6) Enter TTY mode communicating with UPS
-
- Option 7) Quit
-
- SERIAL PORT (SIMPLE SIGNALLING MODE)
-
- Option 1) Test 1 - normal mode
-
- Option 2) Test 2 - no cable
-
- Option 3) Test 3 - no power
-
- Option 4) Test 4 - low battery (requires Test 3 first)
-
- Option 5) Test 5 - battery exhausted
-
- Option 6) Test 6 - kill UPS power
-
- Option 7) Test 7 - run tests 1 through 5
-
- Option 9) Quit
-
- FILES
-
- SEE ALSO
-
- AUTHORS
-
- This page
-
- Software
-
- Contributors
-
This document was created by
man2html,
using the manual pages.
Time: 02:27:47 GMT, April 19, 2024