Monitoring a UPS in Home Assistant: NUT Integration, Add-on and Automations

Pick your architecture first

Home Assistant does not talk to a UPS directly. It talks to a NUT server, which talks to the UPS. Where that server runs depends on where the UPS data cable goes.

Running the NUT add-on on Home Assistant OS

On Home Assistant OS (and supervised installs), a community-maintained Network UPS Tools add-on runs the driver and server for you. Install it from the add-on store (Settings, Add-ons), then configure it. The add-on's configuration typically looks like this in YAML mode:

users:
  - username: nutuser
    password: change-me
    instcmds:
      - all
    actions: []
devices:
  - name: myups
    driver: usbhid-ups
    port: auto
    config: []
mode: netserver
shutdown_host: false

Option names can change between add-on versions, so compare against the add-on's own documentation tab. Two settings deserve attention:

• shutdown_host: when true, the add-on shuts down the Home Assistant host on low battery. That is reasonable for a dedicated HA machine, but read the add-on notes about how it interacts with the UPS power-off sequence.
• mode: netserver: lets other machines on the network connect as NUT clients. Add a separate user for them.

Start the add-on and check its log. A line showing the driver connected to the UPS, without repeated "data stale" warnings, means it is working.

Adding the NUT integration

1. Go to Settings > Devices & services and choose Add integration.
2. Search for Network UPS Tools (NUT).
3. Enter the host: the add-on's hostname (the add-on's documentation lists it, often a0d7b954-nut for the community add-on) or the IP of your NAS or server.
4. Port 3493, plus the NUT username and password. For a Synology server these are commonly monuser and secret; see Synology UPS setup.
5. If the server has more than one UPS, pick the one to add.

The integration creates a device with sensors. Names derive from the UPS name, so a UPS called myups yields entities such as sensor.myups_status, sensor.myups_battery_charge and sensor.myups_battery_runtime. Some sensors are disabled by default; enable the ones you need on the device page.

What the sensors mean

Automations that earn their keep

Alert when the power goes out and comes back

alias: UPS on battery alert
triggers:
  - trigger: template
    value_template: "{{ 'OB' in states('sensor.myups_status_data') }}"
actions:
  - action: notify.mobile_app_your_phone
    data:
      title: "Power outage"
      message: >
        UPS on battery. Charge {{ states('sensor.myups_battery_charge') }}%,
        runtime about {{ (states('sensor.myups_battery_runtime') | int(0) / 60) | round(0) }} min.
mode: single

Add a second automation for the opposite edge (OB disappearing from the status) to confirm power has returned. The raw status entity name varies (it is often a "status data" sensor carrying the flags); check the device page for the exact entity ID. Older Home Assistant versions use trigger:, platform: and service: keys instead of triggers:, trigger: and action:; the visual editor writes the right form for your version.

A reusable "on battery" binary sensor

template:
  - binary_sensor:
      - name: "UPS on battery"
        device_class: problem
        state: "{{ 'OB' in states('sensor.myups_status_data') }}"

With this in place, other automations can simply check binary_sensor.ups_on_battery.

Shed non-essential load

If a smart plug on the UPS feeds something non-essential (a monitor, a lamp, a second access point), turning it off when the UPS goes on battery extends runtime for the things that matter. Wait a minute or two before shedding, so brief flickers do not cause churn.

Testing without waiting for a storm

Automations that only fire during real outages tend to be broken when you finally need them. Test them deliberately, in this order:

1. Check the raw data. Open Developer tools, States, and find the UPS status entity. Note its exact value while on mains (usually OL or OL CHRG).
2. Dry-run the template. Paste your trigger template into the template editor and confirm it evaluates to false now.
3. Simulate the state. In Developer tools, States, you can temporarily set the entity's state to OB. This fires state-based triggers without touching the UPS, which is ideal for checking notification text. The integration overwrites the fake value at its next poll.
4. Do one real test. With the UPS battery charged, unplug the UPS from the wall for two or three minutes. Confirm the notification arrives on your phone over mobile data (turn off Wi-Fi), because during a real outage your home Wi-Fi may be down.
5. Check the recovery path. Plug back in and confirm the "power restored" notification and any load you shed comes back.

A dashboard worth having

A small UPS card on your main dashboard pays for itself the first time the lights flicker. Useful elements:

• Status in plain words (the human-readable status sensor), so anyone in the house can see "On battery" at a glance.
• Battery charge and runtime as gauges, with runtime converted to minutes using a template sensor.
• Load percentage history over a week. A slow upward creep tells you someone has added devices to the battery outlets, which quietly shortens runtime. Compare against the guidance in UPS load percentage.
• Input voltage history where reported. Repeated dips line up with brownouts and explain why the UPS clicks onto battery; see UPS keeps switching to battery.

Long-term statistics on these sensors also give you a cheap, continuous record of power quality at home, which is useful evidence if you ever need to raise a supply complaint with your utility.

Things that catch people out

• The notification path needs power. Put the modem, router, switch and Home Assistant host on battery outlets. See UPS for modem and router.
• Runtime is in seconds. Convert before showing it to people.
• Polling interval. The integration polls the server periodically, so very short events can be missed or show up late. The NUT server's own logs are the authoritative record.
• Energy dashboard. UPS power readings, where available, are often estimates derived from load percentage and nominal rating. They are fine for trends, but not a substitute for a real energy meter. Do not double count a UPS power sensor with smart plugs measuring the same devices.
• Replace battery flag. Alert on RB in the status. It is a cheap early warning that runtime has degraded; see replace battery light.

For deeper NUT configuration, including the server side, see the NUT guide.