Wednesday, September 10, 2014

Getting my UPS to work with Linux

Recently I acquired an UPS to power my home file server. The model is "Eaton 5E 1100i USB", made by Eaton (obviously). Now, to tell you something straight - if you relate Eaton with the high-end PowerWare UPSs from the near past (we used them to power our server room back in the good old days), well... that's OK, but the 5E serier is something I'll never refer as "high-end". Let me explain.

The UPS box came with the following things:
- 1x UPS
- 2x IEC power cords for attaching equipment
...and nothing else. No power cord to power the UPS itself from the grid, no USB cable, no CD/DVD with software. Cool, huh?

First thing I did when got the UPS was to connect it to the power grid so it can immediately start charging the batteries (sitting on the store shelves doesn't improve the battery health, you know). Then I connected the UPS via USB to my laptop and started looking for software, so I can test it on Windows (somehow assuming this will be the easiest way to test USB commnication). Eaton provides a software package called "Eaton UPS Companion", so I went to their site to download it. Unfortunately, if you want to download their software, you'll have to provide them your email, and there's no way around it (it's pretty funny, on the web form asking for your email they say "Hey, please enter your email, we maybe already have your details!" - how the hell is this possible I don't know). So you give them away your email address, and then you receive a download link in your email, where you click and get the software. The SW package was small (2-3MB) and downloads/installs quickly.

Again unfortunately, after installing their software on Windows 7, it just refused to work properly. The SW was unable to connect to the UPS over USB, and in general it was totally non-responsive. What's even cooler is that the SW showed in the system tray and there was no way to stop/exit it. It didn't reacted on menu actions like (start / stop / show). I can admit that giving my email away on "someone out there" and installing arbitrary crap on my box was already enough to piss me off quite a bit, so I decided that half an hour wasted for Windows was enough and rebooted the machine under Debian.

Initially I expected that the Linux UPS setup will be much harder than Windows. So, it turned out to be exactly the opposite. First, connect the UPS to an USB port, and check whether the USB device is "visible" to the OS:

Bus 008 Device 002: ID 0463:ffff MGE UPS Systems UPS

Next you need to install a software package called "nut" (comes from Network UPS Tools):
sudo apt-get install nut

Now you need to configure your UPS, so nut can use it. You have to edit /etc/nut/nut.conf:
sudo mcedit /etc/nut/nut.conf

Now edit /etc/nut/ups.conf and add section for the UPS device itself:
    driver = usbhid-ups
    port = auto
    vendorid = 0463
    pollfreq = 30
You may need to adjust the vendorid to suit your case. The pollfreq setting show how period in seconds between consecutive USB commands to the UPS - you can reduce it, but some UPSs hang if it's too fast (mine works OK with pollfreq = 10). Again YMMV.

Now we can start the driver:
sudo upsdrvctl start

If the tool moans about some issues with starting the driver, you can reboot the machine (not scientific, but it works).

And finally, you can check that your UPS is connected and alive - there are console and GUI tools to do this. The console tool is called "upsc", and you can use it as regular user:
upsc myups

And here's the output for my UPS:
battery.charge: 75
battery.runtime: 1737
battery.type: PbAc
device.mfr: EATON
device.model: 5E 1100i
device.type: ups usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.vendorid: 0463
driver.version: 2.6.4 MGE HID 1.31
driver.version.internal: 0.37
input.voltage: 229.0
outlet.1.status: on
outlet.desc: Main Outlet 1
outlet.switchable: no
output.frequency: 49.9
output.frequency.nominal: 50
output.voltage: 233.0
output.voltage.nominal: 230
ups.beeper.status: enabled
ups.delay.shutdown: 20
ups.firmware: 01.04.0018
ups.load: 12
ups.mfr: EATON
ups.model: 5E 1100i
ups.power.nominal: 1100
ups.productid: ffff
ups.start.battery: yes
ups.status: OL CHRG
ups.timer.shutdown: -1
ups.vendorid: 0463

If battery.charge/battery.runtime fields are "0", you'll have to wait for several minutes until they're populated with actual values.

There's a GUI tool called "NUT-Monitor" and is located in the "nut-monitor" Debian package:
sudo apt-get install nut-monitor

(TODO: Add configuration for handling power events)

On the positive side, things are looking well with the USB communication. The UPS provides lots of details about it's state of charge, voltages/currents, attached loads, etc. It's just better than the good olf days when most of the UPSs (except the most expensive ones) had dumb serial interface with ON/OFF signals, and now even a low-cost UPS has similar features. Also, I'm still to test how this UPS handles power outages (but I think our power company will do this for me in the next evenings).

So, that's it - just 5min to make it work with free/libre software in your favorite OS. It's also possibly to export the UPS status across the local network, so other machines can also use it (for power management or even for logging). Now you can enjoy your freshly power-backed system and don't forget to thank to the NUT Team.

Thanks for reading.

PS: When the UPS is charging, the cooling fan is quite noisy, which freaked me out the first time. This is definitely "no go" if you want to use the UPS in silent environment. The good part is that during normal operation (aka waiting for power outage), the UPS is dead silent.


  1. Great piece of work! I've tried to access my Eaton 5P 850 by their IPP s/w over usb and found it works, sometimes, but not others, it says the USB connection fails or can't connect. I tried your NUT setup and it works a treat, every time I get access using NUT-Monitor. How do I get "upsdrvctl start" run at boot time?

  2. Forgot, I'm running it from ubuntu 18.04.

  3. Wow, 6 years later works like a charm on Raspbian with Eaton 5E 650. Thank you!