Monitoring a UPS with NUT on the Raspberry Pi

In this tutorial, we will be showing you how to set up a NUT server on your Raspberry Pi so you can remotely manage a UPS.

NUT stands for Network UPS Tool and allows a device like your Raspberry Pi to communicate with a UPS and monitor it.

Best of all, NUT lets you broadcast UPS information to other NUT clients. This server functionality allows other systems to access your UPS information and react accordingly.

For example, we use a Raspberry Pi running NUT on our network so the other computers connected to the UPS can read the remaining power and shut down.

NUT is relatively straightforward to set up on the Raspberry Pi, especially if your UPS offers a USB connection.

Before proceeding, you should view the official hardware compatibility list to see if NUT supports your UPS. If your UPS is supported, plug it into your Raspberry Pi.

Equipment

Below is a list of the equipment we used when setting up a NUT server on our Raspberry Pi.

Optional

This tutorial was last tested on a Raspberry Pi 400 running the latest version of Raspberry Pi OS Bullseye.

Installing the NUT Server to the Raspberry Pi

Over the following steps, we will be installing the NUT server to the Raspberry Pi. Luckily, the software was available through the official package repository making this a relatively straightforward process.

1. The first thing we need to do is update our Raspberry Pi’s package list and upgrade any out-of-date packages.

You can complete both of these tasks by using the following command.

sudo apt update
sudo apt upgrade

2. Once the update completes, we can install NUT to the Raspberry Pi by running the command below.

sudo apt install nut

Alongside the core version of NUT, the client and server will be installed by running this command. Additionally, if you use conflicting software such as apcupsd, it may automatically remove it.

Configuring NUT to Read Your UPS

Now that the NUT server is installed on your Raspberry Pi, we can move on to configuring the software to read from the UPS.

Getting your UPS Vendor and Product ID

1. We will need additional information to make it easier for NUT to discover the UPS you connected to your Raspberry Pi.

The easiest way to get information is to list connected USB devices using the following command.

lsusb

2. After running this command, you should see something like what we have shown below. You will want to look for the entry that belongs to your UPS.

In our case, the top line is the one we are after as it belongs to our Cyber Power System UPS.

Bus 001 Device 004: ID 0764:0501 Cyber Power System, Inc. CP1500 AVR UPS
Bus 001 Device 003: ID 0424:ec00 Microchip Technology, Inc. (formerly SMSC) SMSC9512/9514 Fast Ethernet Adapter
Bus 001 Device 002: ID 0424:9514 Microchip Technology, Inc. (formerly SMSC) SMC9514 Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

3. Once you have identified your line, there are a few pieces of information that you require

The two pieces you require are specified directly after “ID“. These are the Vendor ID and Product ID, and they are separated by a semicolon (:).

Bus 001 Device 004: ID 0764:0501 Cyber Power System, Inc. CP1500 AVR UPS

For example, from the above line, we can see our vendor ID is “0764” and our product ID is “0501“. With these in hand, we can modify NUT’s configuration file so that it detects our UPS.

Modifying the NUT UPS Configuration on the Raspberry Pi

4. For NUT to be aware of the UPS connected to your Raspberry Pi, you must modify one of the configuration files.

Run the following command to edit the config file that tells NUT what UPS to talk to.

sudo nano /etc/nut/ups.conf

5. To the bottom of this file, you will want to enter the following lines.

[<UPSNAME>]
driver = <DRIVERNAME>
desc = "<MODEL NAME>"
port = auto
vendorid = <VENDORID>
productid = <PRODUCTID>

You will need to replace a couple of values as you type in these lines.

<UPSNAME> – As you can have multiple UPSs running through the one NUT server on your Raspberry Pi it is crucial to label them.

Replace this block with the name you want to assign your UPS. It can only have lowercase and uppercase letters. For example, “ups” would be a valid name, but “ups mon” would not be.
<DRIVERNAME> – Replace this block with the name of the driver your UPS expects. The recommended driver can be found on the NUT compatibility page.

Most will be able to get away with using the “usbhid-ups” driver.
<VENDORID> – Replace the “VENDORID” text with the ID that you got earlier on in this guide. In our case, the value should be 0764.
<PRODUCTID> – You should swap this value with the product ID that you found earlier on in this tutorial. For our example we will be using the value 0501.

An example of a valid configuration would look like the one below.

[ups]
driver = usbhid-ups
desc = "CP900EPFCLCD"
port = auto
vendorid = 0764
productid = 0501

6. Once you have added your new UPS block to the NUT configuration file, you can save and quit.

Save and quit by pressing CTRL + X, Y, then the ENTER key.

Enable NUT to Be Accessible Outside your Raspberry Pi

7. By default, the NUT server on your Raspberry Pi is designed to only listen on the local IP address. What this means is that clients on the network won’t be able to communicate with the server.

Luckily, NUT allows us to modify and adjust the default behavior so the server will listen to all addresses.

Begin editing the “upsd.conf” configuration file using the following command.

sudo nano /etc/nut/upsd.conf

8. Now add the following line to the bottom of this file. This line will allow your devices to connect and talk to the NUT server.

LISTEN 0.0.0.0 3493

9. With that line added, save and quit by pressing CTRL + X, followed by Y, then the ENTER key.

Setting up a NUT User

10. To set up users, you must modify the “upsd.users” file. This file is where you can define users that can access the NUT server.

You can edit this file using the nano text editor by running the command below.

sudo nano /etc/nut/upsd.users

11. Within this file, add the following to the bottom. These lines define a user called “upsmon“, with a password that you define.

We also define this user as a “primary” node as the UPS is connected to the Raspberry Pi itself. If you are connecting to a remote NUT server then this would be a “secondary” node.

Ensure that you replace “<YOURPASSWORD>” with a password of your choosing. Remember it as you will need it in the next few steps.

[upsmon]
    password = <YOURPASSWORD>
    upsmon primary

12. Once you have modified the user’s configuration, save and quit by pressing CTRL + X, followed by Y, then ENTER.

Configuring the NUT UPS Monitor on your Raspberry Pi

13. The next configuration file we need to modify is the one that controls the “upsmon” system. This system monitors the UPS and tells it how to shut down when necessary.

You can modify this file on your device using the command below.

sudo nano /etc/nut/upsmon.conf

14. We now need to add a line so that NUT will monitor the UPS your Raspberry Pi is connected to.

This is as straightforward as adding the following to the bottom of the file.

Ensure that you replace “<UPSNAME>” with the name you assigned your UPS earlier in this guide. Additionally, you will need to replace “<YOURPASSWORD>” with the password you set in the previous section.

MONITOR <UPSNAME>@localhost 1 upsmon <YOURPASSWORD> primary

15. With this line added to your configuration, you can save and quit again. If you are using nano, you can do this by pressing CTRL + X, followed by the Y key, and finally, ENTER.

Operating NUT as a Net Server on the Raspberry Pi

16. Our next configuration step for the NUT Server on our Raspberry Pi is to enable its network server.

To enable the net server, edit the “nut” configuration file using the command below.

sudo nano /etc/nut/nut.conf

17. Now, within this file, scroll down until you find the following line. Typically, this will be at the bottom of the file.

MODE=none

18. Once you find the “MODE” option replace it with the value shown below.

Next time NUT starts, it will know to launch the net server on the Raspberry Pi.

MODE=netserver

19. With that change made, save and quit by pressing CTRL + X followed by the Y key, then ENTER.

Restarting and Testing the Raspberry Pi’s NUT Server for your UPS

20. After making all those changes, you must restart the NUT server on your Raspberry Pi.

You can restart the server using the following two commands within the terminal.

sudo systemctl restart nut-server
sudo systemctl restart nut-monitor

21. Once the service restarts, we can test whether our NUT server is working and successfully retrieving information from your UPS.

To do this all you need to do is run the following command. The “upsc” command is a call to the NUT client, the value directly after is the name of the UPS that we are polling information from.

Change “ups” to match the name you gave your UPS within the NUT server’s configuration files.

upsc ups

22. Below is an example of the information your Raspberry Pi NUT server can retrieve from your UPS.

Init SSL without certificate database
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 20
battery.mfr.date: CPS
battery.runtime: 9000
battery.runtime.low: 300
battery.type: PbAcid
battery.voltage: 24.0
battery.voltage.nominal: 24
device.mfr: CPS
device.model: CP900EPFCLCD
device.serial: 000000000000
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.synchronous: no
driver.version: 2.7.4
driver.version.data: CyberPower HID 0.4
driver.version.internal: 0.41
input.transfer.high: 260
input.transfer.low: 170
input.voltage: 236.0
input.voltage.nominal: 230
output.voltage: 268.0
ups.beeper.status: disabled
ups.delay.shutdown: 20
ups.delay.start: 30
ups.load: 0
ups.mfr: CPS
ups.model: CP900EPFCLCD
ups.productid: 0501
ups.realpower.nominal: 540
ups.serial: 000000000000
ups.status: OL
ups.test.result: No test initiated
ups.timer.shutdown: -60
ups.timer.start: -60
ups.vendorid: 0764

Enabling a GUI to View your Raspberry Pi NUT Server

Now that you have your Raspberry Pi set up with NUT and monitoring the connected UPS, you may want an easy way of viewing the information it’s gathering.

Luckily, this is relatively simple, as NUT has its own web interface. This web interface gives you an easy way of monitoring your UPS remotely without setting up a NUT client.

As this web server operates using CGI scripts, we will use Apache on our Raspberry Pi for the following steps.

Installing the Nut-GUI Server

1. As we need to install some additional packages, ensure the package list is up to date by using the command below.

sudo apt update

2. Next, install the Apache web server and the NUT-CGI software. “NUT-CGI” will allow you to monitor your Raspberry Pi’s connected UPS from the web.

You can install these additional packages using the following command in the terminal.

sudo apt install apache2 nut-cgi

3. For NUT-GUI to work on our Raspberry Pi, we must modify the “hosts” configuration file.

You can begin editing this file by using the following command.

sudo nano /etc/nut/hosts.conf

4. To the bottom of this file, you will want to enter the following line.

This line defines a new monitor, the UPS to monitor, and assigns it the display name “Local UPS“.

Change “ups” next to “@localhost” if you use a different UPS name.

MONITOR ups@localhost "Local UPS"

5. After you have made this change, save and quit by pressing CTRL + X, followed by Y, then ENTER.

6. Our next step is to enable the “CGI” Apache 2 module.

You can enable this module by running the command below within the terminal.

sudo a2enmod cgi

7. For everything to function, you must restart the Apache web server.

Restart the server by running the command below on your Raspberry Pi.

sudo systemctl restart apache2

Accessing the NUT-CGI Web Interface

8. Now that you have the NUT web server on your Raspberry Pi, you can view the interface it generates.

To access this web interface, you will need to know your Pi’s IP Address. You can easily find this address by using the hostname command.

hostname -I

9. Once you have your Raspberry Pi’s IP address, you can access NUT’s web interface by going to the following URL in your favorite web browser.

http://192.168.0.126/cgi-bin/nut/upsstats.cgi

10. By browsing to the URL you should see the following web interface. This page will allow you to quickly monitor all the UPSs your Raspberry Pi is connected to.

If you want a more in-depth view of your UPS, click the link under the “System” column.

11. If you access the more in-depth view, you will see the vital details of your UPS presented with a simple bar graph.

Conclusion

Hopefully by this point in the tutorial you should now have your Raspberry Pi set up with NUT and be successfully monitoring a UPS.

Thanks to its exhaustive compatibility list, NUT is one of the go-to tools for monitoring a UPS.

Please comment below if you have had any issues with getting a NUT server to run on your Raspberry Pi.

Check out our many other Raspberry Pi projects if you found this guide helpful.

9 Comments

Danube on April 28, 2024 at 6:42 pm

Excellent guide. Made it with a raspberry pi 3D and greencell 1200VA 900W (3D print system).
Works fine with blazer_usb driver.
Thanks you very much 🙂

Steve F. on March 20, 2024 at 9:43 am

Worked perfectly on a PI 5, thanks for writing this up.

Louis Marais on January 5, 2024 at 7:20 pm

Thanks for this tutorial. I was able to set up a generic UPS without any issues using this. I was so looking up to getting this thing working, and in the end it was so easy – I’m sure if I did not have this guide it would have been a nightmare.

Tee on December 5, 2023 at 1:31 pm

Awesome guide. Really clear. Thanks!

Laurette on December 4, 2023 at 8:17 am

Seems that under the “Installing the Nut-GUI Server” section, steps 1-3 of editing the /etc/nut/hosts.conf file is premature as it is not there yet. It is installed via step 5 after which it will exist and can be edited. (Note: yes, you could create it and the install will ask what you want to do about it but I find it’s always best to have the original intended file in place and then edit that). Thanks for these great instructions for setting it all up.

1. Emmet on December 4, 2023 at 1:58 pm
  
  Editor
  
  Hi Laurette,
  
  Thank you for the heads up about the ordering of the steps. I have updated the tutorial to correct it.
  
  Kind Regards,
  Emmet
Ash on November 23, 2023 at 1:45 am

You Sir are a legend! love the write up. very very very impressed!

Matt Johnson on August 14, 2023 at 1:53 pm

In the step “Installing the Nut-GUI Server” the file that needs editing is hosts.conf and not host.conf. The current command is missing an “s”. Instead you should run the following:
sudo nano /etc/nut/hosts.conf

1. Emmet on August 14, 2023 at 10:07 pm
  
  Editor
  
  Hi Matt,
  
  Thank you for the heads up, it is much appreciated. I have now corrected the typo within the tutorial.
  
  Cheers,
  Emmet