apctest(8)
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.conf(5) 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.conf(5)
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.conf(5), apcupsd(8).
The HTML apcupsd manual installed on your system or available online at
http://www.apcupsd.org/
AUTHORS
This page
Trevor Roydhouse (current)
Robert Huff
Software
Adam Kropelin (current Project Manager and Code Maintainer)
Kern Sibbald (former Project Manager and Code Maintainer)
Riccardo Facchetti (former Project Manager and Code Maintainer)
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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
