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

FreeBSD Manual Pages

  
 
  

home | help
APCSMART(8)			  NUT Manual			   APCSMART(8)

NAME
       apcsmart	- Driver for American Power Conversion Smart Protocol UPS
       equipment

SYNOPSIS
       apcsmart	-h

       apcsmart	-a UPS_NAME [-x	option=value ...]

	   Note
	   This	man page only documents	the hardware-specific features of the
	   apcsmart driver. For	information about the core driver, see
	   nutupsdrv(8).

SUPPORTED HARDWARE
       The apcsmart driver should recognize (or	at the very least, work	with)
       the majority of Smart-UPS models	- which	includes Smart-UPS, Matrix-UPS
       and Back-UPS lineups, among few other ones.

       Currently, we can roughly divide	APC hardware into four groups (note
       that the	division isn't strict by any means, and	the borders between
       those are pretty	fuzzy):

       [very] "old" models
	   These models	usually	have old APC logo, white color and no
	   programmable	EEPROM;	you won't find them listed anywhere on APC's
	   site	either.	The support for	those will be usually based on
	   driver's compatibility tables, or if	the model (firmware) is	not
	   listed in those - the driver	will try to follow the very basic
	   subset of features, while still trying to remain useful. Despite
	   "smart" tagname, they often tend to behave in pretty	dumb way (see
	   the section below about shutdown behaviour).

	   Example models:

	   o   Smart-UPS 2000I

	   o   Smart-UPS 900I

       "new" models
	   These models	usually	come from late 1990s / pre-2009	times. They
	   are often referred as "3rd. gen". For the most part,	they have
	   programmable	EEPROM,	report supported commands and capabilites, and
	   should work just fine with the apcsmart driver.

       "microlink" models
	   WARNING: these are not natively supported by	apcsmart (or apcupsd,
	   for that matter, if you're wondering). Around 2007, APC (now	APC
	   Schneider) decided to go back to its	proprietry roots, and all the
	   new models (SMT, SMX, SURTD)	use completely different protocol and
	   cables. If you purchased a new APC UPS - that uses cable with RJ45
	   on the one end, and DB-9 on the other - then	you have such model.
	   Your	only option to support it through NUT is to purchase a "legacy
	   communications card"	- part #AP9620 (google 'AP9620'	for more
	   details). Or	if that's not an option, rely on official software.

       Microsol	models
	   Several Microsol serial models sold in Brazil have been rebranded
	   as APC Back-UPS, and	the model numbers tend to start	with "BZ". If
	   you have one	of these "Nobreaks", they will not work	with the
	   apcsmart driver - please see	the solis(8) driver instead.

	   Example models:

	   o   Back-UPS	BZ1200-BR

	   o   Back-UPS	BZ2200BI-BR

       Another thing to	remember is that Smart protocol	is not USB protocol.
       If you have UPS with both USB and serial	ports, then depending on how
       you connect it, you will	need either apcsmart or	usbhid-ups driver.

CABLING
       This driver expects to see a 940-0024C cable or a clone by default. You
       can switch to the 940-0095B dual-mode cable support with	the 'cable='
       definition described below.

       If your 940-xx24X cable is broken or missing, use this diagram to build
       a clone:

       http://www.networkupstools.org/cables.html#_940_0024c_clone

	   Note
	   The "xx" is either "00" for a short cable, or the number of feet of
	   a longer cable. The "X" is a	letter representing the	minor revision
	   of the physical cable and its connectors ("C" and "E" are commonly
	   found revisions). All minor revisions should	use the	same pin-outs
	   and wiring.

       You can specify alternate cable in ups.conf(5):

       cable=940-0095B

       Alternatively, you can also provide it on the command line using:

       -x cable=940-0095B

TTY MODES
       By default the driver works in canonical	mode, but it proved to be a
       problem in Windows systems. Furthermore there's a possibility of	some
       obscure serial cards or serial-USB converters that could	cause problems
       as well.	You can	use 'ttymode=' option to force non-canonical
       discipline in ups.conf(5):

       ttymode=raw

       Alternatively, you can also provide it on the command line using:

       -x ttymode=raw

	   Note
	   Any other value will	make the driver	work in	the canonical mode.

EXPLANATION OF SHUTDOWN	METHODS	SUPPORTED BY APC UPSES
       APC hardware supports a lot of shutdown methods,	that themselves	can
       differ in behaviour quite a bit,	depending on the model.

       S (soft hibernate)
	   This	is most	basic command present in probably all APC models. It
	   will	hibernate the UPS, and subsequently wake it up when the	mains
	   supply returns.  The	command	doesn't	work if	the UPS	is running on
	   mains.

	   "old" models
	       The behaviour here is unfortunately pretty primitive - when the
	       power returns, the UPS just wakes up. No	grace periods, no min.
	       battery charge condition, etc. This is probably not what	you
	       want.

	   "new" models
	       The behaviour here is as	expected - the power is	cut off	after
	       the EEPROM defined grace	period.	The UPS	will wake up when the
	       power returns, after the	EEPROM defined delay AND if the	EEPROM
	       defined min. battery charge level is met. The delay is counted
	       from the	power's	return.

       CS (aka "force OB hack")
	   This	is a trick to make UPS power down even if it's running on
	   mains. Immediately before issuing S,	"simulate power	failure" is
	   issued. The remaining behaviour is as in S case.

	   The name came from APC CS models, where such	trick was used to
	   power down UPSes in consistent fashion using	only S.	It's better to
	   use @nnn command if your UPS	supports it (and is not	too old, see
	   below).

       @nnn (hard hibernate)
	   This	is basic command used to hibernate UPS regardless if it's
	   running on batteries	or on mains. The option	takes 3	digits
	   argument which can be used to specify additional wakeup delay (in 6
	   minute units).

	   "old" models
	       The behaviour is	- unfortunately	- similary primitive to	S. The
	       UPS unconditionally wakes up after nnn*6	minutes	- it doesn't
	       care if the power returned !  If	nnn = 000, then	UPS will do
	       precisely nothing. On those models you're better	specifying nnn
	       > 0, if you can estimate	the kind of power problems that	might
	       be happening in your environment. Another thing to consider
	       with "old" models - you might lose the connection with the UPS,
	       until it	wakes up (with S, the serial connection	is kept
	       alive).

	   "new" models
	       All the usual variables defined in EEPROM are respected (see
	       S). Additionally, if nnn	> 0, the nnn*6 minutes are added to
	       EEPROM defined delay. UPS will not power	up if it's running on
	       batteries, contrary to what "old" models	used to	do - the
	       combined	delay is counted from the moment of power return.

	   Supposedly there exist models that take 2 digits instead of 3. Just
	   in case, NUT	also supports such variation. You have to provide
	   exactly 2 digits to trigger it (awd option, or argument to one of
	   the supported instant commands).

       K (delayed poweroff)
	   This	is permanent poweroff -	the UPS	will not wake up
	   automatically. On newer units, it will respect applicable EEPROM
	   variables.

       Z (instant poweroff)
	   This	is also	permanent poweroff - the UPS will not wake up
	   automatically. The poweroff is executed immediately.

SHUTDOWN CONTROL BY NUT
       There are three options used to control the shutdown behaviour.

       sdtype=[0-5]
	   This	option takes a single digit (0-5) as an	argument. See below
	   for details.

       advorder=no|[0-4]+
	   This	option takes string of digits as an argument. Methods listed
	   are tried in	turn until one of them succeedes. Note that the
	   meaning of digits is	different from sdtype. See below for details.

       awd=[0-9]{1,3}
	   This	option lets you	specify	additional wakeup delay	used by	@. If
	   you provide exactly 2 digits, the driver will try 2 digits
	   variation (see previous section for more info). Otherwise standard
	   3 digits variation is used.	Note: the time unit is 6 minutes !

       Keep in mind that sdtype	and advorder are mutually exclusive. If
       advorder	is provided, sdtype is ignored.	If advorder is set to 'no',
       sdtype is used instead.

       If nothing is provided, NUT will	assume sdtype=0	- which	is generally
       fine for	anything not too ancient or not	too quirky.

   SDTYPE
       The values permitted are	from 0 to 5. Only one can be specified.
       Anything	else will cause	apcsmart to exit.

       0
	   issue soft hibernate	(S) if the UPS is running on batteries,
	   otherwise issue hard	hibernate (@)

       1
	   issue soft hibernate	(S) (if	on batteries), and if it fails (or on
	   mains) - try	hard hibernate (@)

       2
	   issue instant poweroff (Z)

       3
	   issue delayed poweroff (K)

       4
	   issue "force	OB hack" (CS)

       5
	   issue hard hibernate	(@)

	   Note
	   Hard	hibernate's additional wakeup delay can	be provided by awd.

   ADVORDER
       The argument is either a	word 'no', or a	string of 1 - 5	digits in [0 -
       4] range. Each digit maps to the	one of shutdown	methods	supported by
       APC UPSes. Methods listed in this way are tried in order, until one of
       them succedes.

       If advorder is undefined	or set to 'no',	sdtype is used instead.

       The mapping is as follows:

       0   soft	hibernate (S)

       1   hard	hibernate (@)

       2   delayed poweroff (K)

       3   instant poweroff (Z)

       4   "force OB hack" (CS)

	   Note
	   Hard	hibernate's additional wakeup delay can	be provided by awd.

IGNORING LB STATE
       APC units - even	if they	report LB mode - will not go into shutdown
       automatically. This gives us even more control with reference to	"when
       to actually shutdown PSU". Since	version	2.6.2, NUT supports ignorelb
       option in driver's section of ups.conf(5). When such option is in
       effect, the core	driver will ignore LB state as reported	by specific
       driver and start	shutdown basing	the decision only on two conditions:

       battery.charge <	battery.charge.low

       OR

       battery.runtime < battery.runtime.low

       Of course - if any of the variables are not available, the appropriate
       condition is not	checked. If you	want to	explicitly disable one of the
       conditions, simply override the right hand variable causing the
       condition to always evaluate to false (you can even provide negative
       numbers).

       APC UPSes don't have battery.charge.low - you will have to define it if
       you want	to use such condition (prefix the variable with	override. or
       default.).

       "New" units have	battery.runtime.low, but depending on battery quality,
       firmware	version, calibration and UPS load - this variable can be
       underestimated quite a bit - especially right after going into OB
       state. This in turn can cause LB	to be asserted,	which under normal
       conditions will cause NUT to initiate the shutdown. You might want to
       disable this condition entirely,	when relying on	ignorelb option	(this
       was actually the	main motivation	behind introduction of such feature).

       Simple example:

	   [apc]
	       ignorelb
	       override.battery.charge.low = 15
	       override.battery.runtime.low = -1

       This would cause	apcsmart to go into shutdown only if detected battery
       charge <	15%. Runtime condition is always false in this example.

       You could ask - why bother ? Well, the reason is	already	hinted above.
       APC units can be	very picky about the batteries,	and their firmware can
       underestimate the remaining runtime (especially right after going into
       OB state). ignorelb option and override.* let you remain	in control of
       the UPS,	not UPS	in control of you.

       Furthermore, this allows	to specify conditions similary to how it's
       done in apcupsd daemon, so it should be welcome by people used to that
       software.

SUPPORTED INSTANT COMMANDS
       The apcsmart driver exposes following instant commands:

       shutdown.return
	   executes soft hibernate

       shutdown.return cs
	   executes "force OB hack"

       shutdown.return at:<nbr>
	   executes "hard hibernate" with <nbr>*6 minutes additional wakeup
	   delay (<nbr>	format is the same as of awd option)

       shutdown.stayoff
	   executes "delayed poweroff"

       load.off
	   executes "instant poweroff"

       All the above commands must be issued 2nd time to have any effect (no
       less than 3 seconds, and	no more	than 15	seconds	after the initial
       call). Those commands are mostly	useful for manual testing, when	your
       machine is not powered by the UPS you're	testing.

       Other supported commands:

       o   load.on

       o   test.panel.start

       o   test.failure.start

       o   test.battery.start

       o   test.battery.stop

       o   bypass.start

       o   bypass.stop

       o   calibrate.start

       o   calibrate.stop

PREVIOUS DRIVER	VERSION
       Previous	driver is still	available as apcsmart-old, should there	be any
       need to use earlier version (bugs, incompatiblities with	new
       functionality, etc.). In	due time, apcsmart-old will be phased out
       completely, but this won't happen until the new version gets solid
       exposure	with no	pending	issues.

BUGS
       Some older APC UPS models return	bogus data in the status register
       during a	front panel test. This is usually detected and discarded, but
       some other unexpected values have occasionally slipped through.

       APC UPS models with both	USB and	serial ports require a power cycle
       when switching from USB communication to	serial,	and perhaps vice
       versa.

AUTHOR
       Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
       heavily on the original apcsmart	driver by Russell Kroll). This driver
       was called newapc for a time and	was renamed in the 1.5 series. In
       2.6.2 it	was renamed to apcsmart-old, being superseded by updated
       version with new	features, which	is maintained by Michal	Soltys
       <soltys@ziu.info>

SEE ALSO
       nutupsdrv(8), ups.conf(5), usbhid-ups(8), solis(8)

   Internet resources:
       The NUT (Network	UPS Tools) home	page: http://www.networkupstools.org/

Network	UPS Tools 2.7.3.	  12/29/2015			   APCSMART(8)

NAME | SYNOPSIS | SUPPORTED HARDWARE | CABLING | TTY MODES | EXPLANATION OF SHUTDOWN METHODS SUPPORTED BY APC UPSES | SHUTDOWN CONTROL BY NUT | IGNORING LB STATE | SUPPORTED INSTANT COMMANDS | PREVIOUS DRIVER VERSION | BUGS | AUTHOR | SEE ALSO

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

home | help