Network UPS Tools (NUT)
The Network UPS Tools (NUT) integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to monitor and manage an Uninterruptible Power Supply (UPS) for battery backup, a Power Distribution Unit (PDU), or other similar power device using a NUT
Supported devices
This integration supports hardware devices compatible with
NUT. NUT’s hardware compatibility list is available from the Network
UPS Tools
Prerequisites
You must have a NUT server configured to monitor one or more supported power device(s).
It is not possible to automatically detect a NUT server IP address change. You should therefore configure the NUT server with a static IP address, assign a fixed IP address reservation with DHCP, or use DNS as appropriate for your network.
In addition, you will need a username and password for this integration to log into the NUT server if authentication is required.
Configuration
To add the Network UPS Tools (NUT) device to your Home Assistant instance, use 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.
Manual configuration steps
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 bottom right corner, select the
Add Integration button. -
From the list, select Network UPS Tools (NUT).
-
Follow the instructions on screen to complete the setup.
Setting up the integration requires the following information:
Supported functionality
The username and password configured for the device must be granted
instcmds
permissions on the NUT server to use buttons and
switches. Buttons and switches will not be available if user
credentials are not specified. See the NUT server
documentation
Buttons
This NUT integration will add buttons for NUT server commands available for your device.
The following buttons are available for each switchable outlet:
- Power cycle outlet NAME: Power cycle the named outlet
Switches
This NUT integration will add switches for NUT server commands available for your device.
The following switches are available for each switchable outlet:
- Power outlet NAME: Turn power on/off for named outlet
Data updates
The integration uses pollingData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] to retrieve data from the NUT server. The default polling interval is once every 60 seconds.
Example Resources
Given the following example output from NUT (your variables may differ):
$ upsc ups_name@192.168.11.5
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
values with ups
, battery
, input
and output
prefixes.
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
human-readable version.
Device Actions
A device action is available for each parameterless NUT commandupscmd -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 upsd.users
file:
[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.
Remove integration
This integration follows standard integration removal. No extra steps are required.
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
- Next to the entry, select the three-dot
menu. Then, select Delete.