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
upsmonas 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.confsets the mode, such as standalone, netserver or netclient.ups.confdefines each UPS and its driver.upsd.confcontrols which addresses the server listens on.upsd.usersdefines the users and their permissions.upsmon.confconfigures 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,
upsmonshuts 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_shutdownaction 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
instcmdspermission. - Using a changing IP address for the NUT server. Give it a static address.