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

FreeBSD Manual Pages

  
 
  

home | help
APCTEST(8)		  BSD 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) 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

     +o	 Check that the	UPSCABLE, UPSTYPE and DEVICE configuration directives
	 in the	apcupsd.conf(5)	configuration file have	been set appropri-
	 ately;	and

     +o	 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 depend-
     ing 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 sig-
     nalling 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 fol-
     lowing 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	accu-
     rately 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/Smart-
     Trim (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 con-
     nected 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	acti-
     vates SmartBoost.

   Option 9) View/Change high transfer voltage
     Sets the high voltage level at which the UPS switches to battery or acti-
     vates 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 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 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 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 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	sensi-
	     tive 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	bat-
	     tery or activates SmartBoost.

     Option 10)	Change high transfer voltage

	     Changes the high voltage level at which the UPS switches to bat-
	     tery 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 configura-
	     tion 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 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 v3.14.6

NAME | SYNOPSIS | DESCRIPTION | USB PORT | SERIAL PORT (SMART PROTOCOL MODE) | SERIAL PORT (SIMPLE SIGNALLING MODE) | FILES | SEE ALSO | AUTHORS

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

home | help