Mastering Uninterrupted Smart Home Operation: Integrating Network UPS Tools (NUT) with Home Assistant

In the world of smart homes, reliability is paramount. Your Home Assistant instance acts as the brain, orchestrating everything from lighting and climate control to security systems. But what happens when the power goes out? An abrupt shutdown can corrupt data, damage hardware, and leave your smart home in disarray. This is where a robust Uninterruptible Power Supply (UPS) and its integration with Home Assistant become indispensable.

This guide will walk you through integrating Network UPS Tools (NUT) with Home Assistant, enabling your smart home to monitor power conditions, react intelligently to outages, and perform graceful shutdowns to protect your precious data and hardware.

Why UPS Integration is Crucial for Your Smart Home

Beyond simply keeping devices powered during a blackout, a UPS provides:

• Data Integrity: Prevents file system corruption on your Home Assistant server, especially critical for database files.
• Hardware Protection: Safeguards sensitive electronics from power surges, sags, and spikes.
• Continued Operation: Keeps essential smart home functions (e.g., security cameras, critical lighting, network infrastructure) running for a period.
• Graceful Shutdowns: Allows Home Assistant and its host system to shut down safely before the UPS battery is fully depleted.

What is Network UPS Tools (NUT)?

NUT is a free, open-source software suite that provides a common interface for monitoring and managing various UPS devices. It consists of three main components:

• upsd: The UPS server daemon, which communicates with the UPS.
• upsmon: The client monitor daemon, which can react to UPS events (like power loss, low battery).
• upsc: A command-line client to query UPS status.

Home Assistant leverages NUT to expose your UPS's various sensors and statuses as entities, enabling powerful automations.

Prerequisites

• A UPS with a data communication port (typically USB or Serial). Ensure it's compatible with NUT (most major brands like APC, CyberPower, Eaton are).
• Home Assistant instance (running Home Assistant OS, Supervised, Container, or Core).
• Physical access to connect the UPS data cable to your Home Assistant host or a separate server.

Setting Up NUT for Home Assistant

There are two primary ways to set up NUT for Home Assistant:

Option 1: Using the Home Assistant Add-on (Recommended for Home Assistant OS/Supervised)

This is the simplest method if your Home Assistant instance is running on Home Assistant OS or Supervised.

1. Connect UPS: Plug the UPS's data cable (usually USB) into the USB port of your Home Assistant host machine.
2. Install the Add-on:
   • Navigate to Settings > Add-ons in Home Assistant.
   • Click Add-on Store (bottom right).
   • Search for "Network UPS Tools" and install it.
3. Configure the Add-on:
   • After installation, go to the add-on's Configuration tab.
   • The most crucial part is configuring the ups.conf section. You'll need to specify your UPS model's driver and the port it's connected to.
   • A common configuration for USB-connected UPSes looks like this:
     driver: usbhid-ups
port: auto
desc: "My Home Assistant UPS"
name: myups
   • Replace usbhid-ups with the correct driver if your UPS isn't HID-compliant (consult NUT documentation for your specific model). port: auto usually works for USB.
   • You can also add a username and password under user and password for enhanced security (recommended).
   • Example ups.conf in add-on config:
     

     devices:
       - name: myups
         driver: usbhid-ups
         port: auto
         desc: "My Home Assistant UPS"
         user: nutuser
         password: supersecretpassword

   • Review other settings like override_vars if you need to fine-tune.
4. Start the Add-on: Go to the add-on's Info tab and click Start. Check the logs for errors.

Option 2: Manual Installation on a Separate Linux Server (For Home Assistant Container/Core or Remote UPS)

If your Home Assistant runs in a Docker container, directly on a Linux host (Core), or your UPS is connected to a different server, you'll need to install NUT manually.

1. Install NUT: On your Linux server, open a terminal and run:
   sudo apt update && sudo apt install nut -y (for Debian/Ubuntu-based systems)
   sudo yum install nut -y (for RedHat/CentOS-based systems)
2. Configure nut.conf: Edit /etc/nut/nut.conf and set MODE=NETSERVER.
3. Configure ups.conf: Edit /etc/nut/ups.conf.
   

   [myups]
     driver = usbhid-ups
     port = auto
     desc = "My Home Assistant UPS"

   Add a user and password if you plan to secure it.
4. Configure upsd.conf: Edit /etc/nut/upsd.conf. This defines who can connect to the NUT server.
   

   LISTEN 0.0.0.0 3493
   MAXAGE 10
   STATEPATH /var/run/nut
   POWERDOWNFLAG /etc/nut/upsd.shutdown

   Add an ACCEPT FROM line if you want to restrict access to specific IP addresses.
5. Configure upsd.users: Edit /etc/nut/upsd.users to create a user for Home Assistant.
   

   [nutuser]
     password = supersecretpassword
     actions = SET FSD
     instcmds = ALL
     upsdesc = "Home Assistant UPS Client"

   Remember to match this username and password in Home Assistant.
6. Restart NUT Services: Apply changes by restarting the NUT services:
   sudo systemctl restart nut-server nut-client
   Check logs with journalctl -u nut-server -f for any issues.
7. Firewall (if applicable): Ensure port 3493 (default NUT port) is open on your Linux server if you have a firewall enabled (e.g., UFW).
   sudo ufw allow 3493/tcp

Home Assistant Integration

Once NUT is running and accessible, integrate it into Home Assistant:

1. In Home Assistant, go to Settings > Devices & Services.
2. Click Add Integration (bottom right).
3. Search for "Network UPS Tools (NUT)" and select it.
4. Enter the Host (IP address of the machine running NUT, e.g., 192.168.1.100 or localhost if using the add-on), Port (default 3493), Username, and Password (if configured).
5. Submit the form. Home Assistant should discover your UPS and create various entities.

You'll now see a device representing your UPS, with entities for battery charge, remaining runtime, load, input voltage, UPS status (Online, On Battery), and more.

Best Practices for Managing a Reliable UPS-Integrated Smart Home

1. Monitor Critical Data on Your Dashboard

Add key UPS entities to your Lovelace dashboard for quick oversight:

• sensor.myups_battery_charge (percentage)
• sensor.myups_battery_runtime (minutes remaining)
• binary_sensor.myups_ups_status (Online/On Battery/Low Battery)
• sensor.myups_ups_load (load percentage)

2. Essential Automations for Power Events

These automations are critical for data protection and intelligent power management:

a. Notify on Power Outage / Restoration

automation.yaml example:

- id: 'notify_power_outage'
  alias: 'Notify: Power Outage Detected'
  trigger:
    - platform: state
      entity_id: binary_sensor.myups_ups_status
      to: 'on_battery'
  action:
    - service: notify.mobile_app_your_device
      data:
        message: "⚡️ Power outage detected! Home Assistant is now running on UPS battery."
        title: "Smart Home Alert: Power Outage"
        data:
          priority: high
          ttl: 0
  mode: single

- id: 'notify_power_restored'
  alias: 'Notify: Power Restored'
  trigger:
    - platform: state
      entity_id: binary_sensor.myups_ups_status
      from: 'on_battery'
      to: 'online'
  action:
    - service: notify.mobile_app_your_device
      data:
        message: "✅ Power has been restored. Home Assistant is back on utility power."
        title: "Smart Home Alert: Power Restored"
        data:
          priority: low
  mode: single

b. Graceful Shutdown of Home Assistant Host

This is the most critical automation. It should trigger when the battery reaches a critical level or remaining runtime is too low.

- id: 'graceful_shutdown_ups'
  alias: 'Graceful Shutdown: UPS Critical Battery'
  trigger:
    - platform: numeric_state
      entity_id: sensor.myups_battery_charge
      below: 10  # Trigger when battery charge drops below 10%
      for:
        minutes: 2 # Add a small delay to prevent false triggers
  condition:
    - condition: state
      entity_id: binary_sensor.myups_ups_status
      state: 'on_battery'
  action:
    - service: notify.mobile_app_your_device
      data:
        message: "⚠️ UPS battery critically low! Home Assistant will shut down in 60 seconds."
        title: "Critical Smart Home Alert"
        data:
          priority: high
          ttl: 0
    - delay: "00:00:30" # Give some time for the notification to be seen
    - service: hassio.host_shutdown # Or homeassistant.stop for Core/Container without host shutdown
      # For Home Assistant OS/Supervised, this shuts down the host. 
      # For Home Assistant Core/Container, you might need a script to trigger host shutdown via SSH.
  mode: single

Note for Home Assistant Core/Container users: hassio.host_shutdown will not work. You'll need a different mechanism, like an shell_command executing an SSH command to shut down the remote host, or a script on the host itself triggered by another means (e.g., MQTT).

c. Conserve Battery by Turning Off Non-Essential Devices

- id: 'power_outage_conserve_power'
  alias: 'Power Outage: Conserve Power'
  trigger:
    - platform: state
      entity_id: binary_sensor.myups_ups_status
      to: 'on_battery'
  condition: []
  action:
    - service: light.turn_off
      data:
        entity_id: all # Or specific non-essential lights/devices
    - service: switch.turn_off
      data:
        entity_id: switch.decorative_lights, switch.media_center # Example high-power devices
    - service: notify.mobile_app_your_device
      data:
        message: "Energy saving mode activated due to power outage. Non-essential devices are off."
        title: "Smart Home Power Save"
  mode: single

3. Regular Testing is Key

Do not skip this step! Periodically (e.g., every 3-6 months), perform a controlled power outage test. Unplug your UPS from the wall, verify that the automations trigger as expected, and that your Home Assistant instance shuts down gracefully before the UPS battery is depleted. This validates your setup and builds confidence in your smart home's resilience.

4. UPS Sizing and Placement

• Capacity: Ensure your UPS has enough capacity (VA/Watts) to power your Home Assistant host, network equipment (modem, router, switches), and any other critical smart home hubs for an adequate duration. Aim for at least 15-30 minutes of runtime for graceful shutdowns.
• Ventilation: Place your UPS in a well-ventilated area. UPS batteries generate heat during operation and charging.
• Location: Keep it accessible but out of the way, especially from pets or small children.

5. Security Considerations

If you're running NUT on a separate server, ensure you've configured a strong username and password in upsd.users and restricted access via upsd.conf (ACCEPT FROM) and your firewall. Default NUT installations can be insecure if left exposed.

Conclusion

Integrating Network UPS Tools with Home Assistant is a relatively straightforward yet incredibly impactful step towards a truly robust and reliable smart home. By proactively managing power events, you safeguard your data, extend the life of your hardware, and ensure your Home Assistant remains the dependable heart of your automated living space, even when the lights go out.