Add device actions to NUT integration doc (#24698)

pestevez · bdraco · web-flow · commit a7e3b2d1d02f · 2023-04-23T14:14:47.000-05:00
Co-authored-by: J. Nick Koston &lt;nick@koston.org&gt;
diff --git a/source/_integrations/nut.markdown b/source/_integrations/nut.markdown
@@ -17,9 +17,7 @@ ha_platforms:
 ha_integration_type: device
 ---
 
-The Network UPS Tools (NUT) integration allows you to monitor a UPS
-(battery backup) by using data from a [NUT](https://networkupstools.org/)
-server.
+The Network UPS Tools (NUT) integration allows you to monitor and manage a UPS (battery backup) using a [NUT] https://networkupstools.org/) server. It lets you view their status, receives notifications about important events, and execute commands as device actions.
 
 {% include integrations/config_flow.md %}
 
@@ -72,3 +70,38 @@ values with `ups`, `battery`, `input` and `output` prefixes.
 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.
