Home Lab Projects

Monitoring a UPS With Home Assistant and NUT

Monitor a UPS with Home Assistant through a NUT server, with sensors, battery alerts, shutdown planning and the permissions that enable commands.

On this page
  1. How the pieces fit together
  2. Set up the NUT server first
  3. Add the integration in Home Assistant
  4. What the integration gives you
  5. Alert when the power goes out
  6. Plan shutdowns carefully
  7. Test the setup
  8. Maintenance and safety
  9. Common mistakes

A UPS keeps your equipment running through short power cuts and gives you time to shut down during longer ones. Network UPS Tools (NUT) is the open-source software that talks to a UPS and shares its data over the network. Home Assistant’s Network UPS Tools (NUT) integration connects to a NUT server to show battery status and control outlets. Automations can then send alerts and help you plan shutdowns.

How the pieces fit together

A NUT setup has two roles:

  • The NUT server (upsd) runs on the machine connected to the UPS over USB. It listens on TCP port 3493. The server can be a NAS, a Raspberry Pi, a PC or a VM with the UPS passed through.
  • The NUT client asks the server for data. Home Assistant’s integration is one client. Linux machines can also run upsmon as a client, which shuts them down during a power event.

Home Assistant doesn’t need to be the machine attached to the UPS. Give the NUT server a static IP address or a DHCP reservation, because Home Assistant can’t detect an address change on its own.

Set up the NUT server first

Many USB UPSes, including common APC, CyberPower and Eaton models, use the usbhid-ups driver with port = auto. Before you touch Home Assistant, confirm that the server can read the UPS:

upsc <ups-name>@localhost

If the output shows battery charge, load and status, the server works.

NUT keeps its configuration in several files:

  • nut.conf sets the mode, such as standalone, netserver or netclient.
  • ups.conf defines each UPS and its driver.
  • upsd.conf controls which addresses the server listens on.
  • upsd.users defines the users and their permissions.
  • upsmon.conf configures the monitoring client.

On Home Assistant OS, the NUT add-on’s configuration lets you define users and devices directly. You pass the UPS USB device through to the host or VM.

Add the integration in Home Assistant

Go to Settings > Devices & services and add the Network UPS Tools (NUT) integration. Home Assistant may discover a server on your network. If it doesn’t, add the integration manually with the server’s host name or IP address, port 3493, and a username and password if your server needs them.

The command permission matters only for buttons, switches and device actions. Those need a NUT user with the instcmds permission. Grant it only for the commands you need, rather than for all commands. The NUT server documentation explains how to set it in upsd.users.

What the integration gives you

  • Sensors for battery charge, battery runtime, load, input and output voltage, and a human-readable Status sensor. Only values that your UPS reports appear.
  • Diagnostic sensors. Many are disabled by default. Enable the ones you need from the entity settings.
  • Outlet controls on UPSes with switchable outlets. Each outlet can have a switch and a power-cycle button.
  • Polling every 60 seconds by default.

The Status sensor shows text such as “On Battery, Battery Discharging” when the UPS is running on battery. The exact text depends on your UPS, so check the state in Developer tools before you build a trigger on it. The raw ups.status codes include OL (online), OB (on battery), LB (low battery), CHRG (charging) and RB (replace battery).

Alert when the power goes out

Create an automation that sends a notification when the UPS switches to battery. The trigger is a state change on the UPS status sensor, and the action is a notification. Here is an example in the current YAML format:

alias: Notify when the UPS switches to battery
triggers:
  - trigger: state
    entity_id: sensor.ups_status
    to: "On Battery, Battery Discharging"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.mobile_app_your_phone
    data:
      message: "The UPS lost power and is now on battery."

Replace the sensor and notify entities with your own. Add a second automation for low battery, using a numeric state trigger on battery charge, such as below 25 percent. Choose a threshold that leaves enough time to shut down.

Plan shutdowns carefully

Home Assistant doesn’t shut itself down when the battery runs low. Something else has to do that. The usual options are:

  • A NUT client. On a Linux machine, upsmon shuts the machine down when the server sends a forced shutdown during a power event. In newer NUT releases the roles are called primary and secondary, and the primary sends the forced shutdown to secondaries.
  • A Home Assistant automation. On Home Assistant OS, an automation can call the hassio.host_shutdown action after a condition, such as running on battery with low runtime.

Test a shutdown automation with a generous threshold first. A wrong trigger or a noisy sensor can shut down your Home Assistant host when nothing is wrong. Also plan the order. Shut down devices that depend on the NAS or the Home Assistant host before those hosts go down.

Test the setup

Runtime estimates on consumer UPSes can be inaccurate, especially on older batteries. Test the setup with everyone in the house aware of it. Unplug the UPS from the wall, confirm that the status changes and the notification arrives, then plug it back in. Do this when nothing critical is running, or when you’re ready to handle a shutdown.

You can also start a quick battery test from the NUT server. List the supported commands with upscmd -l <ups-name>, then run test.battery.start.quick if your UPS supports it. A battery test can briefly switch the load to battery.

If the UPS powers a Proxmox host, the Proxmox monitoring guide covers the host side. To keep a history of battery charge, see how to log sensors in InfluxDB and Grafana.

Maintenance and safety

  • Batteries wear out. Sealed lead-acid batteries often last a few years. Write the installation date on the UPS and plan a replacement.
  • Replace a swollen battery immediately. Stop using the UPS until you do.
  • Don’t plug laser printers or space heaters into a UPS battery outlet. They draw large loads that a battery isn’t designed to carry for long.
  • A UPS only protects what’s plugged into it. If your modem and router aren’t on battery, your network drops during an outage.

Common mistakes

  • Assuming Home Assistant shuts itself down. It doesn’t.
  • Trusting runtime estimates without testing. Test them.
  • Forgetting credentials for commands. Buttons and switches won’t work without the instcmds permission.
  • Using a changing IP address for the NUT server. Give it a static address.

The complete guide to home lab projects

Self-Hosted Apps That Integrate With Home Assistant: Immich, Donetick and TeslaMate
Read the guide

Keep exploring

Guides from other topics

All topics →