--- title: Network UPS Tools (NUT) description: Instructions on how to set up NUT sensors within Home Assistant. ha_category: - Button - System monitor - Switch ha_iot_class: Local Polling ha_release: 0.34 ha_domain: nut ha_config_flow: true ha_codeowners: - '@bdraco' - '@ollo69' - '@pestevez' - '@tdfountain' ha_zeroconf: true ha_platforms: - button - diagnostics - sensor - switch ha_integration_type: device related: - url: https://www.networkupstools.org title: Network UPS Tools --- The **Network UPS Tools (NUT)** {% term integration %} 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](https://networkupstools.org/) server. It lets you view the status, receive notifications about important events, and execute commands as device actions for one or more such devices. ## Supported devices This integration supports hardware devices compatible with NUT. NUT's hardware compatibility list is available from the [Network UPS Tools](https://networkupstools.org/) website. ## 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. {% include integrations/config_flow.md %} Setting up the integration requires the following information: {% configuration_basic %} Host: description: "The IP address or hostname of your NUT server." Port: description: "The network port of your NUT server. The NUT server's default port is '3493'." Username: description: "The username to log into the NUT server. This is configured in NUT." Password: description: "The password associated with the username to log into the NUT server. This is configured in NUT." {% endconfiguration_basic %} You can update these settings after installation. To do so, reconfigure the NUT device via {% my integrations title="**Settings** > **Devices & services**" %}, select {% icon "mdi:dots-vertical" %} for the NUT device you wish to update, and select **Reconfigure**. ## Supported functionality {% important %} 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](https://networkupstools.org/documentation.html) for configuration information. {% endimportant %} ### 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 {% term polling %} to retrieve data from the NUT server. The default polling interval is once every 60 seconds. You can also [define a custom polling interval](/common-tasks/general/#defining-a-custom-polling-interval) if needed. ## Example Resources Given the following example output from NUT (your variables may differ): ```yaml $ 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 [command](https://networkupstools.org/docs/user-manual.chunked/apcs03.html) 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: ```bash $ 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: ```text [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. {% include integrations/remove_device_service.md %}