Network UPS Tools

The primary goal of the Network UPS Tools (NUT) project is to provide support for Power Devices, such as Uninterruptible Power Supplies, Power Distribution Units, Automatic Transfer Switches, Power Supply Units and Solar Controllers. NUT provides a common protocol and set of tools to monitor and manage such devices, and to consistently name equivalent features and data points, across a vast range of vendor-specific protocols and connection media types.

NUT provides many control and monitoring features, with a uniform control and management interface. If you are just getting acquainted with NUT, that page also explains the technical design and some possible set-ups.

If you have an UPS at home, the chances it works with NUT are very high. Indeed brand devices have better chances to be actually supported, but at least very basic support should be available for any UPS with an USB connection. There are also UPS that support NUT over the network directly, but they are usually much more expensive than home devices.

NUT is a software that you need to install on a computer (or a rPi) which is located nearby the UPS itself and connected to it via USB cable.

For Gentoo, there is very detailed wiki page that you should take a lot at. Beside the Gentoo specific commands, it will provide a nice overview of how it works.

After you have installed the packages, the following command will show you if your UPS is supported:

 # nut-scanner 
Scanning USB bus.
No start IP, skipping SNMP
No start IP, skipping NUT bus (old connect method)
Scanning NUT simulation devices.
Scanning NUT bus (avahi method).
[nutdev-usb1]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "0463"
        productid = "FFFF"
        product = "Eaton 3S"
        serial = "Blank"
        vendor = "EATON"
        # bus = "001"
        # device = "003"
        # busport = "009"

Note down this output, because this will also become your device setup later on.

What you need to do is setup a NUT server on every device connected to a distinct UPS in your home. This is achieved by editing the following text configuration files:

• /etc/nut/nut.conf
• /etc/nut/ups.conf
• /etc/nut/upsd.conf
• /etc/nut/upsd.users
• /etc/nut/upsmon.conf
• /etc/nut/upssched.conf

Here is my example config:

nut.conf is used to configure the operating mode, and you want a netserver here:

nut.conf

MODE=netserver

ups.conf define the UPS connected to your server, and it's a copy-paste of the nut-scanner output:

ups.conf

[UPS-server]
        driver = "usbhid-ups"
        port = "auto"
        vendorid = "0463"
        productid = "FFFF"
        product = "Eaton 3S"
        serial = "Blank"
        vendor = "EATON"
        bus = "001"
 

please note that i have renamed the device with something more meaningful. Sometimes some non branded UPS might require you to remove bus/product/vendor to work, YMMV.

upds.conf contains some special setup for the daemon that manages the UPS data. In general you don't need to edit it. In my experience, some less branded devies might require a setting a custom MAXAGE. You might want to specify the IP where upsd will listen on:

MAXAGE=150
LISTEN 10.20.30.99 3493

upsd.users defines the users that can access your UPS data. You should define as follows:

upsd.users

[monmaster]
    password = monmaster
    upsmon master

[monslave]
    password = monslave
    upsmon slave

it doesn't really matter, but you should costomize your passwords.

upsmon.conf configure your NUT monitor, you should not need to change it from defaults.

upssched.conf define what your server sohuld do on UPS events, customize as you need. My default is:

upssched.conf

AT ONBATT * START-TIMER onbatt 300
AT ONLINE * CANCEL-TIMER onbatt online
AT LOWBATT * EXECUTE onbatt
AT COMMBAD * START-TIMER commbad 30
AT COMMOK * CANCEL-TIMER commbad commok
AT NOCOMM * EXECUTE commbad
AT SHUTDOWN * EXECUTE powerdown
AT REPLBATT * EXECUTE replacebatt

Home Assistant has a native integration for NUT, which can be found here. Go ahead and install it on your Home Assistant.

At this point, all you need to do is to add a new device from the NUT page in Home Assistant, specify the IP and port of the NUT server, and you are all set!