Release: 
Build: 
Support: 
Monitors uninterruptible power supplies via Network UPS Tools (NUT). All UPS devices connected to a NUT server are automatically discovered and polled.
- Automatic discovery of all UPS devices on a NUT server via
LIST UPS - Dynamic state creation from
LIST VAR— whatever your UPS reports appears as ioBroker states - Proper data types: numeric values as numbers (not strings), with units (V, Hz, A, Ah, %, W, VA, s, °C)
- Parsed
ups.statusflags as individual booleans (online, onBattery, lowBattery, charging, ...) plus computed severity (0–4) - Instant commands (INSTCMD) via button states — beeper control, load management, self-test
- Writable variables (SET VAR) — change UPS settings directly from ioBroker
- Persistent TCP connection with automatic reconnect and exponential backoff
- Network interface selector for multi-homed servers
- Connection test button in the admin UI
- Node.js >= 22
- ioBroker js-controller >= 7.2.2
- ioBroker Admin >= 7.8.23
- A running NUT server (upsd) with at least one UPS configured
| Option | Description | Default |
|---|---|---|
| NUT Server Host | Hostname or IP address of the NUT server | — |
| Port | NUT server port | 3493 |
| Network Interface | Bind outgoing connections to a specific local IP (optional) | all |
| Poll Interval (s) | How often to query the NUT server (2–300) | 15 |
| Username | NUT username (optional — required for commands and writable variables) | — |
| Password | NUT password | — |
| Use TLS (STARTTLS) | Encrypt the connection via STARTTLS | off |
| Require valid certificate | Reject self-signed/invalid certificates (only shown when TLS is on) | off |
Use the Test Connection button to verify the server is reachable and see discovered UPS devices.
About TLS: enabling STARTTLS encrypts the connection so your NUT username and password are no longer sent in clear text over the network. With the default settings it protects against passive eavesdropping, but not against an active man-in-the-middle, because most NUT servers use a self-signed certificate that cannot be verified. For full protection, configure a certificate the client can validate on the NUT server and enable Require valid certificate. The NUT server must be built with TLS support (upsd with CERTFILE/CERTPATH); otherwise the connection test reports a TLS error.
| Option | Description | Default |
|---|---|---|
| Command Timeout (s) | Timeout for individual NUT protocol commands (1–30) | 5 |
| Enable Commands | Allow sending instant commands (INSTCMD) to the UPS | off |
| Enable SET VAR | Allow changing writable UPS variables | off |
Both command features require a NUT user with appropriate permissions configured on the NUT server.
States are organized by NUT domain. The exact set of states depends on what your UPS driver reports.
nut2.0.
├── info.connection — Connection to NUT server (bool)
└── {ups_name}/ — Device (e.g. "ups0")
├── info/
│ └── reachable — UPS responds / data is fresh (bool)
├── battery/
│ ├── battery.charge — Battery level (%, number)
│ ├── battery.charge-low — Low battery threshold (%)
│ ├── battery.runtime — Remaining runtime (s)
│ ├── battery.type — Battery chemistry (string)
│ └── ...
├── device/
│ ├── device.mfr — Manufacturer (string)
│ ├── device.model — Model name (string)
│ ├── device.serial — Serial number (string)
│ └── ...
├── driver/
│ ├── driver.name — NUT driver name
│ ├── driver.version — Driver version
│ └── ...
├── input/
│ ├── input.voltage — Input voltage (V, number)
│ ├── input.frequency — Input frequency (Hz, number)
│ └── ...
├── output/
│ ├── output.voltage — Output voltage (V, number)
│ ├── output.frequency — Output frequency (Hz, number)
│ └── ...
├── ups/
│ ├── ups.load — UPS load (%, number)
│ ├── ups.power — Apparent power (VA, number)
│ ├── ups.realpower — Real power (W, number)
│ ├── ups.status — Raw status string (e.g. "OL CHRG")
│ └── ...
├── status/ — Parsed status flags
│ ├── raw — Original status string
│ ├── display — Human-readable status (e.g. "Online, Charging")
│ ├── severity — 0=OK, 1=Info, 2=Warning, 3=Critical, 4=Emergency
│ ├── online — On line power (bool)
│ ├── onBattery — Running on battery (bool)
│ ├── lowBattery — Battery is low (bool)
│ ├── charging — Battery is charging (bool)
│ ├── discharging — Battery is discharging (bool)
│ ├── replaceBattery — Battery needs replacement (bool)
│ ├── overloaded — UPS is overloaded (bool)
│ ├── forcedShutdown — Forced shutdown in progress (bool)
│ ├── alarm — Alarm active (bool)
│ ├── ecoMode — ECO / high efficiency mode (bool)
│ ├── testing — Self-test in progress (bool)
│ ├── overheat — UPS overheated (bool)
│ └── ... — (19 flags total)
└── commands/ — Instant commands (if enabled)
├── beeper-enable — Button: enable beeper
├── beeper-disable — Button: disable beeper
├── test-battery-start — Button: start battery test
└── ... — (from LIST CMD)
State IDs: the first dot in a NUT variable name is the channel separator; any further dots become dashes. So
battery.charge.lowis stored asbattery.charge-low, and the instant commandtest.battery.startbecomescommands.test-battery-start.
| Level | Meaning | Typical Flags |
|---|---|---|
| 0 | OK | OL, OL CHRG, OL HB |
| 1 | Info | TRIM, BOOST, CAL |
| 2 | Warning | OB (without LB), RB, BYPASS |
| 3 | Critical | OB + LB |
| 4 | Emergency | FSD |
- Verify the NUT server is reachable from the ioBroker host:
nc -zv <host> 3493 - Check firewall rules for TCP port 3493
- Use the Test Connection button in the admin UI
- Ensure Enable Commands is checked in the Advanced tab
- A NUT username and password with
instcmdspermission must be configured - Check the NUT server's
upsd.usersconfiguration
- Ensure Enable SET VAR is checked in the Advanced tab
- The NUT user needs
actions = SETpermission on the NUT server
- Check
info.connection— iffalse, the TCP connection is down - Check the ioBroker log for NUT error codes (e.g.
DATA-STALEmeans the UPS driver lost contact) - Verify the poll interval is appropriate for your setup
- The version history shown in the adapter manager now lists only versions that actually exist for this adapter.
- The poll interval can now go down to 2 seconds — below that the NUT driver itself has no new readings to give.
- Writable yes/no UPS settings (e.g. automatic restart after power returns) can now actually be changed from ioBroker — previously toggling them was silently rejected by the NUT server.
- Device readings now have correct types instead of plain text: yes/no fields become booleans, numeric fields carry their unit, and status, severity and enum fields show a readable label.
- The admin "Test connection" button now reports the real result — a clear error, or the list of discovered UPS devices — instead of always showing "Ok".
- More reliable on slow or flaky networks: no needless drop-and-reconnect, a stalled connection now fails fast instead of hanging, and the adapter recovers instead of getting stuck at startup.
- Clearer status labels: the OFF flag now reads "Off" instead of "Offline", and the on-line flag "On line power" instead of "Online" — so neither is mistaken for a lost network connection.
- When variable writing (SET VAR) is disabled, readings are shown as read-only instead of looking editable but silently ignoring your changes.
- With login credentials configured, a NUT server that has more than one UPS no longer leaves the adapter offline (yellow). Multi-UPS setups with authentication now connect and poll correctly.
Older changelogs can be found there
NUT support in ioBroker goes back to Apollon77 — his iobroker.nut adapter brought the Network UPS Tools protocol to the platform in 2016 and served it until 2025. This adapter is an independent rewrite and shares no code with it.
This adapter is free and open source. If you find it useful, consider buying me a coffee:
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