Provided by: nut_2.0.3-4build1_i386 bug

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

COMMANDS:

       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. 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                    BELKINUNV(8)