Network UPS Tools (NUT) Smart-Home-Integration, kostenlos und Open Source
Monitor the status, load and battery runtime of the UPS devices on your NUT servers.
Veröffentlicht von prohand
- Geräte
- Version 2.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
The Network UPS Tools (NUT) integration lets Gladys retrieve values and states from UPS devices exposed by a reachable NUT upsd server on the local network.
This integration is designed for monitoring. It does not send shutdown, restart, or configuration commands to UPS devices.
Prerequisites
Your UPS must already work in NUT. From the machine hosting Gladys, the NUT server should answer the following command, after replacing the placeholders with your own values:
upsc <ups-name>@<server-address>
By default, upsd listens on TCP port 3493. Ensure that both network rules and NUT ACLs allow access from Gladys.
Configuration
- Open Integrations, then Network UPS Tools (NUT).
- In the Configuration tab, enter the first
upsdserver; its host is required. - Add up to four additional servers in the optional slots when needed.
- For each server, keep port
3493unless your installation uses another port. Enter NUT credentials when authentication is required. - Choose a refresh interval. The default value of 300 seconds is appropriate for most installations. Gladys polls devices once a minute at most: a longer interval is applied on the closest polling tick.
- Save, then use Test NUT connections.
Choosing the refresh interval
Every published value is kept in the Gladys history, and a UPS exposes up to twelve values. A short interval therefore grows the database quickly: at 60 seconds, a single UPS writes around 17,000 rows per day, against around 3,500 with the default interval of 300 seconds.
To reduce that volume further, the integration only publishes the values that changed since the previous reading; a value that stayed stable is republished at least once an hour so it is never displayed as stale. Go down to 60 seconds only when you need fine-grained monitoring — the remaining runtime during an outage, for instance — and raise the interval up to 86,400 seconds when you would rather spare the database.
Once the connection succeeds, Gladys discovers every UPS returned by the NUT server. Each UPS appears as a distinct Gladys device in discovery. In the Discovery tab, click Add for every UPS you want to integrate: you can add several devices independently. The list is rebuilt on each scan from the NUT LIST UPS command.
Available information
NUT drivers do not all report the same variables, so the integration only creates sensors for information actually provided by each UPS.
| Domain | Possible values |
|---|---|
| Battery | Charge, runtime, voltage, and temperature |
| Power | Input/output voltage and current |
| Load | Load percentage, real power, and apparent power |
| UPS | Temperature, status, and alarms |
Values are published only when they are numeric and actually reported by the driver. NUT text statuses are read during communication but are not published as Gladys features, keeping the discovery payload compatible with Core versions that do not yet recognize the text category.
Widget, scenes and actions (Gladys 5.1)
The integration requires Gladys 5.1 or later.
"UPS" widget
In Dashboard → Edit → Add a widget, choose UPS, then the UPS to show. The widget displays:
- the battery charge (gauge) and the remaining runtime;
- the UPS load and the input voltage;
- a 24 h chart (battery charge and load);
- the state (on mains, on battery, low battery…), the NUT alarms, the power and the server;
- a Refresh button, which reads the UPS right away. It never sends a command to the UPS.
Scene triggers
In the scene editor, Integrations category:
| Trigger | When |
|---|---|
| UPS: power failure, on battery | the UPS switches to battery (OB) |
| UPS: power restored | the UPS is back on mains (OL) |
| UPS: battery low | NUT reports a low battery (LB) |
| UPS: battery to replace | NUT asks for a replacement (RB) |
- Leave the UPS field empty to react to every UPS.
- The state is checked every minute, whatever the refresh interval: a power cut is seen within a minute.
- Variables available in the scene:
ups_name,status,battery_charge(%),battery_runtime(min),load(%). - When the integration starts, the first reading is the reference: no event is sent for a UPS already on battery.
"Read a UPS status" scene action
It reads the chosen UPS and returns to the following actions: ups_name, status (online, on_battery, low_battery, forced_shutdown, off, bypass, unknown), on_battery, low_battery, replace_battery, battery_charge, battery_runtime (min), load, input_voltage. A reading the UPS does not report is left out.
Example: every morning, read the UPS status then send a message with the remaining runtime.
Troubleshooting
| Symptom | Recommended checks |
|---|---|
| No UPS is found | Check every host, port, firewall, and that at least one UPS is configured in each ups.conf. |
| Access or authentication error | Check the ACLs in upsd.conf and credentials defined in upsd.users. |
| Some values are missing | Run upsc <ups>@<server>; Gladys can only create variables exposed by your NUT driver. |
| Stale data | A stable value is only rewritten once an hour, which is expected. Beyond that, verify that the NUT driver still communicates with the hardware and inspect the upsd logs. |
| The Gladys database grows too fast | Raise the refresh interval: the amount of history is directly proportional to it. Every UPS you add writes its own history. |
| Adding a UPS fails with "incomplete or invalid device" | Update the integration. That rejection (HTTP 422) came from features published without their min and max bounds, which are now always declared. |
| Values never change after adding the device | Update the integration: devices are now published with periodic polling enabled. |
| Some features are displayed without a name or an icon | Update the integration, then add the UPS again from the Discovery tab so its existing features are updated: the load and the apparent power were published on a category/type pair the Gladys front-end does not know how to draw. |
| The UPS load is displayed as "Unknown" | Update the integration, then add the UPS again from the Discovery tab: the load (ups.load) is now published on a category that lets Gladys show its name, "Load". |
For detailed errors, open the integration logs in Gladys. You can also set LOG_LEVEL=debug for more detailed logs.
Resources
The official NUT network protocol specification details the discovery and read commands used by this integration.
Konfigurationseinstellungen
Diese Einstellungen fragt Network UPS Tools (NUT) in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| NUT servers | section | Nein | Configure one or more reachable upsd servers. Every UPS exposed by every configured server is discovered as a separate Gladys device. |
| Server 1 host | string | Ja | IP address or DNS name of the first NUT upsd server. |
| Server 1 port | number | Nein | The default NUT TCP port is 3493. |
| Server 1 username (optional) | string | Nein | |
| Server 1 password (optional) | secret | Nein | Required when a username is configured. |
| Server 2 host (optional) | string | Nein | |
| Server 2 port | number | Nein | |
| Server 2 username | string | Nein | |
| Server 2 password | secret | Nein | |
| Server 3 host (optional) | string | Nein | |
| Server 3 port | number | Nein | |
| Server 3 username | string | Nein | |
| Server 3 password | secret | Nein | |
| Server 4 host (optional) | string | Nein | |
| Server 4 port | number | Nein | |
| Server 4 username | string | Nein | |
| Server 4 password | secret | Nein | |
| Server 5 host (optional) | string | Nein | |
| Server 5 port | number | Nein | |
| Server 5 username | string | Nein | |
| Server 5 password | secret | Nein | |
| Refresh interval (s) | number | Nein | How often the readings are written to the Gladys history. Each one is a row in the database: keep 300 s unless you need finer measurements. The UPS status is still checked every minute for the scenes. |
So installierst du Network UPS Tools (NUT) in Gladys
- Öffne in Gladys Integrationen: Network UPS Tools (NUT) erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/prohand/gladys-nut:2.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/prohand/gladys-nut.
Network UPS Tools (NUT) benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Network UPS Tools (NUT) ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von prohand veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation