NAME
belkinunv - Driver for Belkin "Universal UPS" and compatible
NOTE
This man page only documents the hardware-specific features of the
belkin driver. For information about the core driver, see
nutupsdrv(8).
SUPPORTED HARDWARE
The belkinunv driver is known to work with the Belkin Universal UPS
models F6C800-UNV and F6C120-UNV, and is expected to work with other
Belkin Universal UPS models. The driver only supports serial
communication, not USB.
The Trust UPS and older Belkin units are not supported by this driver,
and neither are the Belkin Home Office models (F6H500-SER and so
forth). However, some Belkin models, such as the Regulator Pro, are
supported by the belkin(8) driver, and the Home Office models are
supported using the genericups(8) driver with upstype=7.
SOFT SHUTDOWN WORKAROUND
One problem with the Belkin Universal UPS is that it cannot enter a
soft shutdown (shut down the load until AC power returns) unless the
batteries are completely depleted. Thus, one cannot just shut off the
UPS after operating system shutdown; it will not come back on when the
power comes back on. Therefore, the belkinunv driver should never be
used with the -k option. Instead, the -x wait option is provided as a
workaround.
When called with the -x wait option, belkinunv behaves as a standalone
program (i.e., it does not fork into the background). It performs one
simple task: it connects to the UPS, waits for AC power to return, and
then exits with status 0.
This is meant to be used in a shutdown script as follows: during a
shutdown, after all filesystems have been remounted read-only, and just
before the system would normally be halted: check /etc/killpower (or
similar) to see if this shutdown was caused by upsmon(8), and if yes,
call belkinunv -x wait. If AC power comes back on, belkinunv exits, and
things should be arranged so that the system reboots in this case. If
AC power does not come back on, the UPS will eventually run out of
batteries, kill the computer's power supply, and go into soft shutdown
mode, which means everything will reboot properly when the power
returns. In either case, a deadlock is avoided.
In addition, if an optional integer argument is given to the -x wait
option, this causes belkinunv to wait not only for AC power to be
present, but also for the battery charge to reach the given level. I
use this as part of my startup scripts, to ensure that the batteries
are sufficiently charged before the computer continues booting. This
should be put very early in the startup script, before any filesystems
are mounted read/write, and before any filesystem checks are performed.
Several other -x options are provided to fine-tune this behavior. See
OPTIONS below for detailed descriptions. See EXAMPLES below for
examples of how to use belkinunv in shutdown and startup scripts.
OPTIONS
See also nutupsdrv(8) for generic options. Never use the -k option with
this driver; it does not work properly.
-x wait[=level]
When this option is used, belkinunv does not fork into the
background, but behaves as a standalone program. It
connects to the UPS and waits until AC power is present. If
level is specified, it also waits until the battery charge
reaches at least the given level in percent. Then, and only
then, belkinunv exits. In addition, while belkinunv runs in
this mode, it displays a status line with information on
the UPS status and battery level. This is intended for use
in the computer's shutdown and startup scripts, as
described under SOFT SHUTDOWN WORKAROUND above.
-x nohang This option only has an effect when used in conjunction
with the -x wait option. It causes belkinunv to exit if a
connection with the UPS cannot be established or is lost,
instead of retrying forever, which is the default behavior.
The -x nohang option should be used in a startup script, to
ensure the computer remains bootable even if the UPS has
been disconnected during the power failure (for instance,
you attached your computer to a generator, carried it to a
neighbor's house, or whatever).
-x flash This option only has an effect when used in conjunction
with the -x wait option. It causes the UPS load to be shut
off for a short time ("flashed") just after the AC power
has returned and the requested battery level (if any) has
been attained. This is useful if slaves are attached to
this UPS; the flash will cause all of them to reboot. Note
that, due to the design of the Belkin UPS hardware, the
load shutdown lasts ca. 1-2 minutes; a shorter flash cannot
be performed reliably. Also, the computers will reboot at
the scheduled time, on battery power if necessary, even if
AC power fails again in the meantime. This should not be a
problem, as your startup scripts can catch this situation.
-x silent This option only has an effect when used in conjunction
with the -x wait option. It suppresses the status line
which belkinunv would normally print.
-x dumbterm This option only has an effect when used in conjunction
with the -x wait option. It changes the way in which
belkinunv prints its status line. Normally, terminal
control sequences are used to overwrite the same line with
new status information, each time the status is updated.
This may not work on all terminals. If the -x dumbterm
option is given, each status update is written on a new
line.
VARIABLES:
battery.charge
battery.runtime
not supported by all hardware.
battery.voltage
battery.voltage.nominal
driver.version.internal
input.frequency
input.frequency.nominal
e.g. 60 for 60Hz
input.sensitivity
writable: normal/medium/low
input.transfer.high
writable: high transfer voltage point in V
input.transfer.low
writable: low transfer voltage point in V
input.voltage
input.voltage.maximum
input.voltage.minimum
input.voltage.nominal
output.frequency
output.voltage
ups.beeper.status
writable. Values: enabled/disabled/muted. This variable
controls the state of the panel beeper. Enabled means sound
when the alarm is present, disabled means never sound, and
muted means the sound is temporarily disabled until the
alarm would normally stop sounding. In the muted state, the
beeper is automatically turned back on at the next event
(AC failure, battery test, etc). Also, the beeper can't be
turned off during a critical event (low battery). Note that
not all UPS models support the "disabled" state.
ups.firmware
ups.load
ups.model
ups.power.nominal
e.g. 800 for an 800VA system
ups.status a list of flags; see STATUS FLAGS below.
ups.temperature
not supported by all hardware.
ups.test.result
ups.delay.restart
time to restart (read only)
ups.delay.shutdown
time to shutdown (read only). This is always a multiple of
60 seconds.
ups.type ONLINE/OFFLINE/LINEINT. This describes the basic layout of
this UPS (for GUI clients which want to draw an animated
picture of power flow). An offline UPS has a direct
connection from AC input to AC output, and also a
connection from AC input to the battery, and from the
battery to AC output. An online UPS lacks the direct
connection from AC input to AC output, whereas a line
interactive UPS lacks the connection from AC input to the
battery.
COMMANDS:
beeper.enable, beeper.disable, beeper.mute
enable, disable or mute the panel beeper. Note that if the
beeper is muted, it is automatically turned back on at the
next event (AC failure, battery test, etc). Also, the
beeper can't be turned muted during a critical event (low
battery).
reset.input.minmax
reset the variables input.voltage.minimum and
input.voltage.maximum.
shutdown.reboot
shut down load immediately for ca. 1-2 minutes
shutdown.reboot.graceful
after 40 second delay, shut down load for ca. 1-2 minutes
shutdown.stayoff
shut down load immediately and stay off. The only way it
can be turned back on is by manually pressing the front
panel button.
test.battery.start, test.battery.stop
start/stop 10 second battery test
test.failure.start, test.failure.stop
start/stop "deep" battery test
STATUS FLAGS:
OB load is on battery, including during tests
OFF load is off
OL load is online
ACFAIL AC failure. Note that this refers to the AC input, and thus
it is not the same as "OB". An AC failure can occur at any
time, for instance, during a battery test, or when the UPS
load is off.
OVER overload
OVERHEAT overheat
COMMFAULT UPS fault
LB low battery
CHRG charging
DEPLETED the battery is depleted. When the UPS raises this flag, it
simultaneously switches off the load.
RB replace battery
EXAMPLES
Here is an example for how belkinunv should be used in a computer's
shutdown script. These commands should go in the very last part of the
shutdown script, after all file systems have been mounted read-only,
and just before the computer halts. Note that belkinunv must be
installed in a directory which is still readable at that point.
# NEAR END OF SHUTDOWN SCRIPT:
# if shutdown was caused by UPS, perform Belkin UPS workaround.
if [ -f /etc/killpower ] ; then
echo "Waiting for AC power, or for UPS batteries to run out..."
/usr/bin/belkinunv -x wait /dev/ttyS1
# we get here if the power came back on. Reboot.
echo "Power is back. Rebooting..."
reboot
fi
And here is an example of how to use belkinunv in the startup script.
These commands should go near the beginning of the startup script,
before any file systems are mounted read/write, and before any file
system integrity checks are done.
# NEAR BEGINNING OF STARTUP SCRIPT:
# if we are recovering from a power failure, wait for the UPS to
# charge to a comfortable level before writing anything to disk
if [ -f /etc/killpower ] ; then
echo "Waiting for UPS battery charge to reach 60%..."
/usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1
fi
EXIT STATUS
When used normally, belkinunv forks into the background and its
diagnostics are the same as for all NUT drivers, see nutupsdrv(8).
When used with the -x wait option, the exit status is normally 0. If
the -x nohang option has also been specified, an exit status of 1
indicates that communication with the UPS was lost. If the -x flash
option has been specified, an exit status of 2 indicates that the timed
shutdown has failed.
EXTRA ARGUMENTS
This driver does not support any extra settings in ups.conf(5).
SEE ALSO
The documentation for the protocol used by this UPS:
belkin-universal-ups.html
The core driver:
nutupsdrv(8)
Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
AUTHOR
Peter Selinger <selinger@users.sourceforge.net>
Sun Dec 7 2003