Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
APCTEST(8)		    System Manager's Manual		    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)  con-
       figuration  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 configura-
       tion variables as well and the performing of a battery runtime calibra-
       tion. It	also  provides a simple	TTY chat mode which allows direct  in-
       teraction 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	direc-
	   tives  in  the apcupsd.conf(5) configuration	file have been set ap-
	   propriately;	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 de-
       pending 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 de-
       pending 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 ac-
       curately	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 volt-
       age fluctuations	- (H)igh, (M)edium or (L)ow. The higher	the  sensitiv-
       ity, the	faster the UPS will switch to battery power or activate	Smart-
       Boost/SmartTrim	(features  that	avoid using battery power provided the
       under/over voltage is within 12%	of nominal).  This setting should nor-
       mally be	set to High unless the UPS  switches  to  battery  power  fre-
       quently,	 in which case a less sensitive	setting	will preserve UPS bat-
       teries... 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  ac-
       tivates SmartBoost.

   Option 9) View/Change high transfer voltage
       Sets the	high voltage level at which the	UPS switches to	battery	or ac-
       tivates 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 calibra-
       tion 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 recali-
       brate the remaining runtime counter that	it maintains and therefore re-
       port a more accurate estimated runtime.	As batteries age, they tend to
       hold less charge, so the	UPS's internal runtime counter may not be  ac-
       curate after several years.

       It  is  recommended that	battery	runtime	calibration be performed annu-
       ally. Performing	it too often shortens the lifetime of the UPS  batter-
       ies.

   Option 11) Test Alarm
       This  option  will cause	the UPS	alarm beeper to	sound for several sec-
       onds.

   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 vari-
       able 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  calibra-
       tion  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  recali-
       brate the remaining runtime counter that	it maintains and therefore re-
       port a more accurate estimated runtime.	As batteries age, they tend to
       hold  less charge, so the UPS's internal	runtime	counter	may not	be ac-
       curate after several years.

       It is recommended that battery runtime calibration be  performed	 annu-
       ally.  Performing it too	often shortens the lifetime of the UPS batter-
       ies.

   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 configura-
       tion 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 bat-
	       tery 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 batter-
	       ies... if the connected equipment can tolerate the power	 qual-
	       ity.

       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 bat-
	       tery 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 con-
	       nected 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 configu-
	       ration	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	possi-
       ble 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 at-
       tached 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.

apctest	v3.14.6		       January 10, 2009			    APCTEST(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=apctest&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help