• 1. Introduction
• 2. Protocol Description
• 3. The NUT Belkin Universal UPS driver
• 4. The Belkin "Bulldog Plus" driver
• 5. Some useful utilities

1. Introduction

I recently bought a Belkin "Universal UPS" (model number F6C800-UNV). Like millions of other people, I decided to buy a UPS ("Uninterruptible Power Supply") after the major power outages which occurred in the U.S. and Ontario in August 2003. I had read that the Belkin UPS supported Linux, and it was widely available in stores near me (Radio Shack, Target, Office Depot, etc.). The price was not bad, and so I decided to try it.

On the surface, Belkin seems Linux-friendly, because they provide a Linux version of their "Bulldog Plus" UPS management software. This software is not included on the CD Rom which ships with the UPS, but one can download it from Belkin's website.

But unfortunately, the Bulldog Plus software is not as useful as it should be. It has many bugs (see Bugs in Bulldog), and it cannot be configured to allow an unsupervised recovery (the user must press the front panel button to restart the UPS after a power failure).

Since the specifications of the protocol were not available, I decided to do some detective work and to decipher the protocol myself. The results are described on a separate web page, the Protocol Description Page. The information reported there is necessarily incomplete, but it seems that I have covered the most important aspects of the protocol.

Unfortunately, there is one serious problem with the "Universal UPS" firmware: there is no command which causes the UPS to go into "soft shutdown" mode, which means, to shut off the load until AC power returns. This makes unsupervised recovery from power failures tricky and awkward (see Soft Shutdown Workaround on the protocol description page for a suggested solution).

On balance, the Belkin UPS works fine, but the lack of a "soft shutdown" command is annoying. If you are thinking about buying a UPS, I think currently APC is a better choice than Belkin at approximately the same price (see e.g. Linux and the APC Back-UPS ES). Maybe Belkin will come up with an improved version of their firmware in the future.

2. Protocol description

• Protocol Description.

3. The NUT Belkin Universal UPS driver

NOTE: The belkinunv NUT driver requires a modification to the system's startup/shutdown scripts to enable an unsupervised shutdown/recovery. The necessary changes are described in the section Soft Shutdown Workaround on the protocol description page.

NOTE FreeBSD Users: Ryan Winland has reported that the "standalone" mode of the "belkinunv" NUT driver does not work properly in FreeBSD. The problem seems to be that FreeBSD uses a non-portable mechanism for locking its serial ports. Ryan sent me a modified version belkinunv.c that is supposed to work in FreeBSD. I have not personally tested this, but I am posting it here in the hope that it might be useful to others.

4. The Belkin "Bulldog Plus" driver

News. In November 2003, Belkin has released version 3.01.16 of this software (see the Bulldog Download Site). Some bugs have been fixed, while many others remain. One useful new feature of version 3.01.16 is that they provide a new "configure" command-line program which allows you to configure shutdowns etc, rather than using the X-windows "monitor" program. This is useful for systems that don't have X-Windows installed.

Bugs in Bulldog 3.01.16

• upsd: an AC failure leaves the system in a state where the UPS is off and does not come back on when the AC power returns. The user must press the front panel button to restart the UPS. Therefore, an unsupervised recovery is not possible.
• monitor: voltage sensitivity cannot be set. It is always "regular". In fact, when trying to change the voltage sensitivity, the Linux software sends an invalid command string to the UPS. On the other hand, the Linux upsd works correctly with the Windows monitor, so the bug must be in the Linux monitor.
• upsd: sometimes crashes when the monitor first connects to it.
• monitor: many of the controls don't work. Particularly in the "History" dialog, pressing "Update" causes the monitor to freeze.
• S99bulldog: first line must be "#!/bin/sh" not "# /bin/sh" - otherwise this cannot be started from another shell.

• upsd: UPS poweroff does not work. After the operating system halts, the UPS is supposed to shut itself off after a delay. However, it just sits there.
• upsd: the upsd program writes a temporary file "uname.tmp" to the root directory. Unfortunately, if the root directory is mounted read-only (eg, it's read-only media), the write fails. This problem is trivially fixed by patching the upsd binary. Namely, at file offsets 0x23C1C and 0x23C34 are the strings "uname -a uname.tmp" and "uname.tmp", respectively. I patched the two "uname.tmp" strings to be "/tmp/UPSD". (Thanks to Dean Gibson for this information).
• upsd: the upsd program does a DNS lookup from its own hostname to an IP address, EVERY SECOND. Since I log DNS queries, this means 604,800 extra lines in my weekly DNS logs (ugh). Adding the required hostname-to-IP mapping to my /etc/hosts file solved this problem. (Thanks to Dean Gibson for this information).

Improved System V-type startup scripts (provided by Dean K. Gibson).

For those Linux users who use RedHat or a similar System V-type daemon start/stop mechanism, Dean Gibson has created a working "ups-belkin" script that can be copied to /etc/init.d and then activated via "chkconfig --add ups-belkin". Note that the script runs the daemon under the username of "ups" rather than "root" (helpful for security reasons). This requires that the "/usr/local/bulldog/Command.Shutdown" file be changed to:

  /usr/bin/sudo   /sbin/shutdown -h now

  ups     ALL = NOPASSWD: /sbin/shutdown

5. Some useful utilities

• console.c. A standalone C program for communicating with the UPS on a kind of "console". The user can read and write individual registers, as well as display the state of the UPS. This is useful for experimenting with the UPS hardware. Be careful though - writing random values into register might render your UPS unusable. You may also want to make sure your computer's power supply is not plugged into the UPS while you play with it, or else you'll find yourself shutting down your computer unintentionally.
• ttyspy.c. A standalone program which can be used to listen to communication on a serial port. The idea is to connect two serial ports together.

  Scenario 1: your UPS is connected at /dev/ttyS1, and you tell the UPS driver (which runs on the same machine) to connect to /dev/ttyp0. Then you run

       ttyspy /dev/ptyp0 /dev/ttyS1
  

  and start the UPS driver program, and voila! The communication between the driver and the UPS is established, while ttyspy prints a copy of all communications to stdout. Note: /dev/ttyp0 is a so-called pseudo-terminal, and it is internally connected to /dev/ptyp0, a so-called "master". Thus anything you write on /dev/ptyp0 can be read on /dev/ttyp0 and vice versa (just like two "real" serial ports which have been connected by a null-modem cable). Also note: the master must be opened first, so you must start ttyspy before starting the UPS driver.

  Scenario 2: your UPS is connected to /dev/ttyS1 on machine A. The driver you are testing runs on machine B (which might be running a different operating system), and talks to serial port X on machine B. You use a null-modem cable to connect serial port X on machine B to serial port /dev/ttyS0 on machine A. Then you run

       ttyspy /dev/ttyS0 /dev/ttyS1
  

  on machine A. You are now listening to the communication between the driver and the UPS.
• simulator.c. A standalone C program for simulating a Belkin Universal UPS. This program will attach itself to a serial port master and pretend to be a Belkin Universal UPS. Well, actually, it is not fully functional: it ignores any commands that try to write to a register. You run e.g.

       simulator /dev/ptyp0
  

  and then tell the driver to talk to /dev/ttyp0. There is also the notion of a "state file", which is a text file with entries of the form register value, as in:

      0x18 1189
  

  When starting the simulator as

       simulator device statefile
  

  it will continually read the statefile, which you may edit while the simulator runs. You can use this to figure out how different registers affect the driver.