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

FreeBSD Manual Pages


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

       apcsmart	- Driver for American Power Conversion Smart Protocol UPS

       apcsmart	-h

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

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

       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 capabilities,
	   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	proprietary 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.

       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:

	   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):


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

       -x cable=940-0095B

       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):


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

       -x ttymode=raw

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

       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

	   "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

	   "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.

	   There's a delay between "simulate power failure" and	S - by default
	   set to 3.5s.	You can	control	it through cshdelay option (allowed
	   values are from 0 to	9.9).

	   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

       @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 wake-up delay (in
	   6 minute units).

	   "old" models
	       The behaviour is	- unfortunately	- similarly 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

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

       There are three options used to control the shutdown behaviour.

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

	   This	option takes string of digits as an argument. Methods listed
	   are tried in	turn until one of them succeeds. Note that the meaning
	   of digits is	different from sdtype. See below for details.

	   This	option lets you	specify	additional wake-up 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.

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

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

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

	   issue instant poweroff (Z)

	   issue delayed poweroff (K)

	   issue "force	OB hack" (CS)

	   issue hard hibernate	(@)

	   Hard	hibernate's additional wake-up delay can be provided by	awd.

       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 succeeds.

       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)

	   Hard	hibernate's additional wake-up delay can be provided by	awd.

       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


       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

       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

       "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:

	       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 similarly	to how it's
       done in apcupsd daemon, so it should be welcome by people used to that

       The apcsmart driver exposes following instant commands:

	   executes soft hibernate

       shutdown.return cs
	   executes "force OB hack"

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

	   executes "delayed poweroff"
	   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 is still	available as apcsmart-old, should there	be any
       need to use earlier version (bugs, incompatibilities 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.

       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

       Nigel Metheringham <> (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

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

   Internet resources:
       The NUT (Network	UPS Tools) home	page:

Network	UPS Tools 2.7.4.	  03/01/2021			   APCSMART(8)


Want to link to this manual page? Use this URL:

home | help