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 the options below for detailed descriptions. See the 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]

-x nohang

-x flash

-x silent

-x dumbterm

VARIABLES

battery.charge, battery.runtime

battery.voltage, battery.voltage.nominal, input.frequency, input.frequency.nominal

input.sensitivity

input.transfer.high

input.transfer.low

input.voltage, input.voltage.maximum, input.voltage.minimum, input.voltage.nominal, output.frequency, output.voltage, ups.beeper.status

ups.firmware, ups.load, ups.model, ups.power.nominal

ups.status

ups.temperature

ups.test.result, ups.delay.restart

ups.delay.shutdown

ups.type

COMMANDS

beeper.enable, beeper.disable, beeper.mute

reset.input.minmax

shutdown.reboot

shutdown.reboot.graceful

shutdown.stayoff

test.battery.start, test.battery.stop

test.failure.start, test.failure.stop

STATUS FLAGS

OB

OFF

OL

ACFAIL

OVER

OVERHEAT

COMMFAULT

LB

CHRG

DEPLETED

RB

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

AUTHOR

Peter Selinger <selinger@users.sourceforge.net>