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.