belkinunv - Driver for Belkin "Universal UPS" and compatible

This man page only documents the hardwarespecific features of the belkin driver. For information about the core driver, see nutupsdrv(8).

The belkinunv driver is known to work with the Belkin Universal UPS models F6C800UNV and F6C120UNV, 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 (F6H500SER 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.

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 readonly, 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 finetune this behavior. See OPTIONS below for detailed descriptions. See EXAMPLES below for examples of how to use belkinunv in shutdown and startup scripts.

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

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

writable. Values: yes/no. This variable determines whether the panel beeper is on or off. Note that the beeper is automatically turned back on at the next event (AC failure, battery test, etc). It can be turned off when it is already beeping. Also, the beeper can't be turned off during a critical event (low battery).

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.timer.restart

time to restart (read only)

ups.timer.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.

beeper.on, beeper.off

turn the panel beeper on or off. Note that the beeper is automatically turned back on at the next event (AC failure, battery test, etc). It can be turned off when it is already beeping. Also, the beeper can't be turned off 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. 12 minutes

shutdown.reboot.graceful

after 40 second delay, shut down load for ca. 12 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

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

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 readonly, 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

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.

This driver does not support any extra settings in ups.conf(5).

The documentation for the protocol used by this UPS:

The core driver:

Internet resources:

Peter Selinger <selinger@users.sourceforge.net>