belkinunv



BELKINUNV(8)                Network UPS Tools (NUT)               BELKINUNV(8)




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  nutups-
       drv(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 communica-
       tion, 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 sup-
       ported 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 bat-
       teries, 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  exam-
       ples 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 con-
                   nects 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 belki-
                   nunv  prints  its  status  line. Normally, terminal control
                   sequences are used to overwrite the same line with new sta-
                   tus  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 connec-
                   tion 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 connec-
                   tion 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.volt-
                   age.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  diag-
       nostics 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 indi-
       cates  that communication with the UPS was lost. If the -x flash option
       has been specified, an exit status of 2 indicates that the timed  shut-
       down 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)

Man(1) output converted with man2html