Local Power Resilience: Connecting a Volt Polska USB UPS to Fedora, NUT, and Home Assistant

Having a backup power supply is essential for data integrity during power grid fluctuations.

This post outlines the step-by-step process to connect a Volt Polska USB UPS directly to a Fedora Linux laptop, monitor it with Network UPS Tools (NUT), and expose its real-time metrics to Home Assistant and your AI assistant, Antigravity (agy).

1. Hardware Detection

When connected via USB, the Volt Polska UPS is typically detected as a Cypress-based USB-to-Serial converter. Run lsusb to verify:

$ lsusb
Bus 001 Device 021: ID 0665:5161 Cypress Semiconductor USB to Serial

2. Installing and Configuring NUT on Fedora

Install the NUT packages via DNF:

sudo dnf install -y nut nut-client nut-xml

A. Set Standalone Mode (/etc/ups/nut.conf)

Ensure the service runs a local monitor and server:

MODE=standalone

B. Define the UPS Device (/etc/ups/ups.conf)

Configure the nutdrv_qx driver (which replaces the deprecated blazer_usb driver) for your product IDs:

[volt_ups]
    driver = nutdrv_qx
    port = auto
    vendorid = 0665
    productid = 5161
    subdriver = cypress

C. Allow Connections from Docker (/etc/ups/upsd.conf)

Bind the server daemon to localhost and the Docker bridge gateway IP (172.17.0.1) so the Dockerized Home Assistant can communicate with the host:

LISTEN 127.0.0.1 3493
LISTEN 172.17.0.1 3493

D. Define User Credentials (/etc/ups/upsd.users)

Create the access credentials for Home Assistant:

[homeassistant]
    password = homeassistant_password
    upsmon master

3. Resolving USB Group Permissions

The NUT drivers run under the unprivileged nut system user. Since Fedora’s default udev rules map product ID 5161 to the dialout group (permissions 664), we must add nut to the dialout group and reload udev:

sudo usermod -aG dialout nut
sudo udevadm control --reload-rules
sudo udevadm trigger

4. Enabling and Starting Services

Start the driver and the main daemon server using systemd:

sudo systemctl enable --now nut-driver@volt_ups
sudo systemctl enable --now nut-server.service

Verify that the server successfully communicates with the device:

$ upsc volt_ups@localhost
battery.voltage: 13.4
input.voltage: 235.4
ups.load: 25
ups.status: OL

5. Integrating with Home Assistant GUI

To bring these sensors into Home Assistant, use the native Network UPS Tools (NUT) integration:

1. Navigate to Settings ➔ Devices & Services ➔ Add Integration.
2. Select Network UPS Tools (NUT).
3. Configure the connection details:

• Host: 172.17.0.1 (the Docker bridge IP of the host laptop)
• Port: 3493
• Username: homeassistant
• Password: homeassistant_password

1. Home Assistant will discover the device and auto-create entities for battery charge, voltage, load, status, and input/output voltages.

6. Antigravity (agy) Integration

To query these states, we created a custom CLI script at get_ups_status.sh:

$ /home/gvoina/scripts/get_ups_status.sh
Volt Polska UPS Status:
  - Connection Status: Online (Utility Power)
  - Input Voltage: 234.9 V
  - Output Voltage: 236.4 V
  - Load: 30%
  - Battery Voltage: 13.4 V

Add the command to your rulebook at .agents/AGENTS.md:

### 2. Network & Power Infrastructure Diagnostics
* **Volt Polska UPS status**: `bash /home/gvoina/scripts/get_ups_status.sh`

Now you can check your workspace power health from anywhere:

agy "What is the status of my laptop UPS?"

agy will run the helper script and format the real-time battery status for you!