Network UPS Tools (NUT)
The Network UPS Tools (NUT) integration allows you to monitor and manage a UPS (battery backup) using a NUT server. It lets you view their status, receives notifications about important events, and execute commands as device actions.
Adding Network UPS Tools (NUT) to your Home Assistant instance can be done via the user interface, by using this My button:
Network UPS Tools (NUT) can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.
If it wasn’t discovered automatically, don’t worry! You can set up a manual integration entry:
Browse to your Home Assistant instance.
In the sidebar, select Settings.
From the configuration menu, select Devices & Services.
In the bottom right, select the Add Integration button.
From the list, search and select Network UPS Tools (NUT).
Follow the instructions on screen to complete the setup.
Given the following example output from NUT (your variables may differ):
$ upsc [email protected] ups.timer.reboot: 0 battery.voltage: 27.0 ups.firmware.aux: L3 -P ups.mfr: American Power Conversion battery.runtime.low: 120 ups.delay.shutdown: 20 ups.load: 19 ups.realpower.nominal: 600 battery.charge.warning: 50 battery.charge.low: 10 ups.vendorid: 051d ups.timer.shutdown: -1 ups.test.result: No test initiated ups.firmware: 868.L3 -P.D battery.mfr.ups.serial: 3B1519X19994 ups.productid: 0002 battery.runtime: 2552 battery.voltage.nominal: 24.0 battery.type: PbAc ups.mfr.ups.status: OL ups.model: Back-UPS RS1000G ups.beeper.status: disabled battery.charge: 100 input.sensitivity: medium input.transfer.low: 88 input.transfer.high: 147 input.voltage: 121.0 input.voltage.nominal: 120 input.transfer.reason: input voltage out of range output.current: 1.10 output.frequency: 60.20 output.voltage: 121.50 output.voltage.nominal: 120
Use the values from the left hand column. Support is included for most
UPS Status - human-readable version
An additional virtual sensor type
ups.status.display is available
translating the UPS status value retrieved from
ups.status into a
A device action is available for each parameterless NUT command supported by the device. To find the list of supported commands for
your specific UPS device, you can use the
upscmd -l command followed by the UPS name:
$ upscmd -l my_ups Instant commands supported on UPS [my_ups]: beeper.disable - Disable the UPS beeper beeper.enable - Enable the UPS beeper test.battery.start.quick - Start a quick battery test test.battery.stop - Stop the battery test
These commands will be available as device actions in Home Assistant, allowing you to interact with your UPS.
User Credentials and Permissions
To execute device actions through the NUT integration, you must specify user credentials in the configuration. These credentials are stored in the
upsd.users file, part of the NUT server configuration. This file defines the usernames, passwords, and permissions for users accessing the UPS devices.
No actions will be available if no user credentials are specified for a given device.
Ensure the user you specify has the required permissions to execute the desired commands. Here’s an example of a user with command permissions in the
[my_user] password = my_password actions = SET instcmds = ALL
In this example, the user
my_user has permission to execute all commands (
instcmds = ALL).
Please note that Home Assistant cannot determine whether a user can access a specific action without executing it. If you attempt to perform an action for which the user does not have permission, an exception will be thrown at runtime.