Network UPS Tools

Dieser Adapter liest unterbrechungsfreie Stromversorgungen über einen NUT-Server (Network UPS Tools). Er spricht nie direkt mit der USV: Die USB- oder Netzwerkverbindung zur Hardware gehört dem NUT-Server, der Adapter ist einer seiner Clients. Deshalb beginnt jede Einrichtung auf dem Rechner, an dem die USV hängt.

Die README ist die Kurzfassung. Diese Seite geht eine vollständige Einrichtung durch.

1. Sicherstellen, dass ein NUT-Server läuft

Es braucht einen Rechner, auf dem upsd läuft und mindestens eine USV eingerichtet ist — ein Linux-Host, ein NAS (Synology, QNAP und UGREEN bringen NUT mit) oder ein Raspberry Pi mit der USV am USB.

Auf diesem Rechner prüfen:

upsc -l                 # listet die USV-Namen, z. B. "ups0"
upsc ups0               # zeigt alle Werte dieser USV

Gibt upsc -l nichts aus, liegt das Problem auf der NUT-Seite und der Adapter kann nicht helfen — zuerst den Treiber in Ordnung bringen (/etc/nut/ups.conf, danach upsdrvctl start).

2. Den Server für den Adapter erreichbar machen

upsd lauscht nur auf localhost, solange man ihm nichts anderes sagt. In /etc/nut/upsd.conf:

LISTEN 0.0.0.0 3493

Danach upsd neu starten. Port 3493/TCP muss zwischen ioBroker-Host und NUT-Server offen sein.

Viele NAS-Systeme betreiben NUT in einem „USV-Server"-Modus mit einer eigenen Freigabeliste in der Weboberfläche — die IP-Adresse des ioBroker-Hosts muss dort eingetragen sein.

3. Einen Benutzer anlegen (optional, aber empfohlen)

Zum Lesen der Werte braucht es überhaupt keine Anmeldung. Ein Benutzer wird nur für zwei Dinge gebraucht: die USV schalten (Befehle) und Variablen schreiben. Eintrag in /etc/nut/upsd.users:

[iobroker]
    password = etwas-langes-waehlen
    upsmon secondary
    actions = SET
    instcmds = ALL

Zwei Zeilen mit verschiedenen Aufgaben:

• upsmon secondary ist das, was eine Anmeldung überhaupt möglich macht. Der Adapter meldet sich bei jedem (Wieder-)Verbinden an, auf einer kurzen zweiten Verbindung, ausschließlich um Ihnen zu sagen, ob die Zugangsdaten funktionieren. Ohne diese Zeile wird die Anmeldung abgelehnt — siehe die häufigen Fragen, das ist kein Fehler.
• actions und instcmds entscheiden, was der Benutzer tatsächlich tun darf. upsd prüft sie je Befehl, unabhängig von der Anmeldung.

Nach dem Bearbeiten upsd neu starten.

4. Instanz in ioBroker anlegen

Adapter installieren, Instanz anlegen, Reiter Verbindung ausfüllen:

Verbindung testen drücken. Die Antwort benennt, was wirklich geprüft wurde: ob die Verbindung verschlüsselt ist, wie viele USVen der Server anbietet und — wenn Zugangsdaten eingetragen sind — ob die Anmeldung akzeptiert wurde.

Danach speichern. Der Adapter verbindet sich, erkennt jede USV am Server und legt die Datenpunkte an.

Wie oft sollte abgefragt werden?

Schneller als der NUT-Treiber seine Daten auffrischt, bringt nichts. In /etc/nut/ups.conf hat der Treiber zwei Einstellungen: pollinterval (wie oft der Status aufgefrischt wird, Vorgabe 2 s) und pollfreq (der ganze Wertesatz, Vorgabe 30 s bei USB-Treibern). Alle 15 Sekunden ist ein sinnvoller Mittelweg; deshalb beginnt die Einstellung bei 2 Sekunden — schneller würde nur Werte erneut lesen, die sich nicht geändert haben.

Wer von einem Stromausfall im Moment des Geschehens erfahren will statt beim nächsten Abruf, senkt nicht das Intervall, sondern nutzt die Ereignis-Klingel aus den häufigen Fragen.

5. Die Verbindung verschlüsseln (optional)

Ohne TLS gehen Benutzername und Passwort im Klartext über das Netz. Wenn das in Ihrer Umgebung zählt: upsd kann mit TLS-Unterstützung gebaut werden und bietet dann STARTTLS:

1. Am Server CERTFILE (oder CERTPATH) in der upsd.conf einrichten.
2. Im Adapter TLS verwenden (STARTTLS) anhaken.

In der Voreinstellung prüft der Adapter das Zertifikat nicht — das verschlüsselt gegen Mitlesen, erkennt aber keinen Mann-in-der-Mitte, weil fast jeder NUT-Server ein selbstsigniertes Zertifikat verwendet.

Für echten Schutz zusätzlich Gültiges Zertifikat erfordern anhaken und bei CA-Zertifikatsdatei eine PEM-Datei auf dem ioBroker-Host angeben, gegen die geprüft werden kann — die eigene Zertifizierungsstelle oder das selbstsignierte Serverzertifikat selbst. Die Datei wird nur gelesen, solange die strenge Prüfung an ist; ein Pfad, der von einem früheren Versuch übrig geblieben ist, schadet nicht.

Wurde der NUT-Server ohne TLS gebaut, sagt der Verbindungstest das, statt still auf Klartext zurückzufallen.

6. Die USV aus ioBroker schalten (optional)

Zwei Schalter im Reiter Erweitert öffnen die Schreibrichtung, beide sind bewusst aus:

• Sofortbefehle aktivieren legt je Befehl, den die USV anbietet, eine Taste an (Signalton, Selbsttest, Last abschalten …). Der Kanal commands erscheint erst, wenn das an ist und Zugangsdaten hinterlegt sind — upsd prüft Befehlsrechte gegen einen benannten Benutzer. Sein Text-Datenpunkt commands.execute führt einen Befehl mit Wert aus, etwa load.off.delay 120.
• Beschreibbare Variablen aktivieren macht die USV-Variablen, die der Server als schreibbar meldet, auch in ioBroker schreibbar.

Beides braucht die passenden Rechte in der upsd.users (Schritt 3). Mit den Last-Befehlen vorsichtig umgehen: load.off nimmt allem den Strom, was an der USV hängt.

Wie es weitergeht

• Datenpunkte — was der Adapter anlegt und was die einzelnen Teile bedeuten.
• Häufige Fragen — unter anderem sofortige Ereignis-Meldungen über upsmon.

Changelog

0.17.0 (2026-09-25) — stable

• New: a UPS command that needs a value, such as a delay, can be sent through the new commands.execute data point, written the way upscmd takes it
• New: when the NUT server tracks commands, the log says whether the driver really carried out a command or a new setting, not only that it was sent
• New: every device shows a pictogram for its NUT device type in the object tree — UPS, PDU, solar charge controller, power supply or transfer switch
• Fixed: the connection to the NUT server no longer drops during long poll intervals — the adapter keeps it alive while it is idle
• Fixed: apparent power, real power and percentages carry the right unit and role, and writable temperatures, voltages and currents are settable levels
• Fixed: text values such as test results, contact states or ups.conf settings stay text instead of turning into numbers or being discarded
• Fixed: a word or an empty value in a measurement, such as LoadTooLow, leaves the data point empty instead of keeping an old number, without a warning
• Fixed: renamed data points keep the rooms and functions you assigned them to, and a unit or explanation that no longer applies is removed
• Fixed: a UPS that is missing from the NUT server for a moment keeps its data points and history; it is removed only after three polls without it
• Fixed: the status severity stays empty when the status names no power source, instead of claiming OK for a UPS that is off or still starting
• Fixed: command buttons follow the driver's command list — buttons of commands it no longer offers disappear, and a UPS without commands gets none
• Fixed: values containing #, quotes or backslashes are read correctly; writing a value with # is refused with an explanation, as NUT drivers cannot report it back
• Fixed: a TLS certificate problem stops the retries with one clear message, and a UPS reporting several value ranges shows the full range
• Improved: names and explanations for every variable and command of the NUT 2.8.5 catalog in all eleven languages, including outlets, groups and sensors
• Improved: the warning sign marks exactly the commands that can cut power or stop the driver; switching something on is never marked
• Changed: the upsmon connection is documented as a small helper script, which keeps working with the NUT releases after 2.8.5

0.16.0 (2026-09-15) — stable

• Fixed: every adapter start silently removed the status severity, the device type, every dropdown and every bounded value from the rooms and functions the user had assigned them to
• Fixed: when a dropdown list or a value range really shrinks, the data point keeps its value, its recording settings and its room and function assignments
• Fixed: a data point that is renamed by an update keeps its room and function assignments, exactly as it already kept its recording settings
• Fixed: a UPS without a desc in ups.conf lost its manufacturer + model name on the first reconnect and was called by its config name until the next restart
• Fixed: after a fatal TLS error on a reconnect the adapter kept polling a connection that no longer existed and promised a retry that never came
• Fixed: stopping the instance while the NUT server was unreachable could leave two error lines in the log
• Improved: dropdown lists and value ranges are no longer rewritten on every start and every reconnect when nothing changed — less load on the object database and on every adapter listening to it
• Improved: the adapter reads its object tree once per discovery instead of once per data point — a lighter start on large installations
• Improved: a value written to a data point the UPS reports as read-only is ignored quietly instead of producing an error
• Improved: a UPS reported without a description by a non-standard NUT server no longer goes missing

0.15.1 (2026-09-07)

• New: ten more data points explain themselves — the battery date, the UPS's own clock, the three driver versions, the UPS identifier, the UPS type and the USB vendor and product IDs
• Fixed: the battery maintenance date is the date of the NEXT change or service, not of the last one — its name said the opposite in all eleven languages
• Improved: setting up the upsmon trigger is one line in upsmon.conf instead of a shell script, and points at the rest-api adapter; the older simple-api path stays documented

0.15.0 (2026-09-07)

• Fixed: a data point no longer holds a value of the wrong kind — a reading that stops matching the data point's type is discarded with one warning instead of being written into it
• Fixed: a NUT server that is switched off or restarting no longer makes the instance look broken — the adapter names the server it cannot reach and keeps retrying
• Fixed: value limits taken from the UPS disappear again when the UPS stops reporting them, instead of standing forever and causing warnings about every value outside them
• Fixed: credentials containing a space are now refused with an explanation instead of a bare protocol error nobody can act on
• Fixed: enabling instant commands now says why no command buttons appear when the UPS does not answer the command list
• Fixed: a UPS variable without a dot in its name is now writable, and can no longer take over one of the adapter's own channels
• Fixed: over a third of the data points carried an English label in every language — 157 more variable names are now translated into all eleven
• Fixed: the phases of a three-phase UPS, the sensors of a multi-sensor probe and the individual outlets no longer all share one name — each keeps the marker that says which one it is
• Fixed: the outlet buttons of a PDU are now named and explained like every other command instead of showing their raw NUT name
• New: explanations for the battery voltage, battery temperature, battery health and input current, which stood without one next to explained siblings

0.14.0 (2026-09-04)

• Fixed: a certificate file left over in the settings no longer stops the adapter — it is only read while strict certificate checking is actually switched on
• Fixed: value lists of writable data points stay in your language instead of falling back to the raw NUT wording after the first poll
• Fixed: the connection test no longer reports an error when only the credentials are refused — it says so and confirms that reading works, matching what the adapter does
• Fixed: the connection test now answers in your language when something goes wrong, not only when it succeeds
• Fixed: a UPS that disappears from the NUT server and comes back gets its manufacturer and model name again instead of keeping the bare UPS name
• Fixed: renamed data points of the adapter itself now reach existing installations instead of only new ones
• Fixed: enabling instant commands without credentials no longer fails silently — the adapter now explains why no command buttons are created
• New: detailed user documentation in English and German is now part of the repository and shown in the ioBroker documentation portal

License

MIT License

Copyright (c) 2026 krobi krobi@power-dreams.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Developed with assistance from Claude.ai