NUT Setup - ebaauw/homebridge-ups GitHub Wiki
Before configuring Homebridge UPS, you need to install NUT, setup and configure your UPS device, and set permissions for Homebridge UPS to access it.
How to do this is beyond the scope of Homebridge UPS, and I do not provide support for this.
See your OS documentation, the NUT documentation, or try man upsd
.
For reference, I list my setup for Synology DSM 7.1 and for Raspberry Pi OS bullseye below.
Setup
Homebridge UPS connects to the primary computer, that communicates with the UPS device, over a USB, or serial connection, or over the network using SNMP.
This is the host running upsd
(and typically also upsmon
).
It does not connect to secondary computers, that only run upsmon
).
See NUT Feature for details.
Verify that NUT is installed on your primary computer and locate the configuration files, typically in /etc/nut
or /etc/ups
.
You need to configure your UPS device(s) in ups.conf
.
Make sure to use the correct driver for your UPS device (e.g. usbhid-ups
for UPS devices connected over USB).
See the comments in ups.conf
, or try man 5 ups.conf
for details.
Homebridge UPS uses the same network connection to upsd
as upsmon
.
Make sure upsd
accepts incoming connections from the host running Homebridge.
Typically this is specified through LISTEN 0.0.0.0
in upsd.conf
, see the comments in that file, or try man 5 upsd.conf
.
Also make sure any firewall allows the connection from Homebridge UPS.
By default upsd
listens on TCP port 3493.
If you want to control the UPS, rather than just monitoring it, you need to define a username and password in upsd.users
, with actions = SET
and instcmds = ALL
.
See the comments in upsd.users
or try man 5 upsd.users
for details.
If the username or password is missing or incorrect, upsd
will simply ignore any command that changes the UPS state, causing a timeout.
Verify
Check that the UPS has been setup correctly by issuing (on the primary computer):
$ upsc -l
Init SSL without certificate database
ups
In this example, upsd
communicates with one UPS device, named ups
.
Check that the UPS device can be queried and reports something by:
$ upsc ups
Init SSL without certificate database
battery.charge: 100
battery.charge.low: 10
battery.charge.warning: 50
battery.date: 2001/09/25
battery.mfr.date: 2021/05/24
battery.runtime: 3168
battery.runtime.low: 120
battery.type: PbAc
battery.voltage: 13.3
battery.voltage.nominal: 12.0
device.mfr: American Power Conversion
device.model: Back-UPS ES 850G2
device.serial: xxxxxxxxxxxx
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.synchronous: no
driver.version: 2.7.4
driver.version.data: APC HID 0.96
driver.version.internal: 0.41
input.sensitivity: medium
input.transfer.high: 266
input.transfer.low: 180
input.transfer.reason: input voltage out of range
input.voltage: 232.0
input.voltage.nominal: 230
ups.beeper.status: enabled
ups.delay.shutdown: 20
ups.firmware: 938.a2 .I
ups.firmware.aux: a2
ups.load: 4
ups.mfr: American Power Conversion
ups.mfr.date: 2021/05/24
ups.model: Back-UPS ES 850G2
ups.productid: 0002
ups.realpower.nominal: 520
ups.serial: xxxxxxxxxxxx
ups.status: OL
ups.test.result: No test initiated
ups.timer.reboot: 0
ups.timer.shutdown: -1
ups.vendorid: 051d
Next, check the server running Homebridge can connect to upsd
on the primary computer (pi4
in this example),
using the ups
command-line utility bundled with Homebridge UPS:
$ ups -H pi4 info
{
"version": "Network UPS Tools upsd 2.7.4 - http://www.networkupstools.org/",
"apiVersion": "1.2",
"devices": {
"ups": {
"description": "pi4",
"nCients": "5",
"clients": [
"127.0.0.1",
"192.168.xxx.xx1",
"192.168.xxx.xx2",
"192.168.xxx.xx3",
"192.168.xxx.xx5"
],
"commands": [
"beeper.disable",
"beeper.enable",
"beeper.mute",
"beeper.off",
"beeper.on",
"load.off",
"load.off.delay",
"shutdown.reboot",
"shutdown.stop",
"test.battery.start.deep",
"test.battery.start.quick",
"test.battery.stop",
"test.panel.start",
"test.panel.stop"
],
"constants": {
"battery.charge": 100,
"battery.charge.low": 10,
"battery.charge.warning": 50,
"battery.date": "2001/09/25",
"battery.mfr.date": "2021/05/24",
"battery.runtime": 3168,
"battery.runtime.low": 120,
"battery.type": "PbAc",
"battery.voltage": "13.3",
"battery.voltage.nominal": 12,
"device.mfr": "American Power Conversion",
"device.model": "Back-UPS ES 850G2",
"device.serial": "xxxxxxxxxxxx",
"device.type": "ups",
"driver.name": "usbhid-ups",
"driver.parameter.pollfreq": 30,
"driver.parameter.pollinterval": 2,
"driver.parameter.port": "auto",
"driver.parameter.synchronous": "no",
"driver.version": "2.7.4",
"driver.version.data": "APC HID 0.96",
"driver.version.internal": "0.41",
"input.sensitivity": "medium",
"input.transfer.high": 266,
"input.transfer.low": 180,
"input.transfer.reason": "input voltage out of range",
"input.voltage": 230,
"input.voltage.nominal": 230,
"ups.beeper.status": "enabled",
"ups.delay.shutdown": 20,
"ups.firmware": "938.a2 .I",
"ups.firmware.aux": "a2",
"ups.load": 4,
"ups.mfr": "American Power Conversion",
"ups.mfr.date": "2021/05/24",
"ups.model": "Back-UPS ES 850G2",
"ups.productid": 2,
"ups.realpower.nominal": 520,
"ups.serial": "xxxxxxxxxxxx",
"ups.status": "OL",
"ups.test.result": "No test initiated",
"ups.timer.reboot": 0,
"ups.timer.shutdown": -1,
"ups.vendorid": "051d"
},
"variables": {
"battery.charge.low": 10,
"battery.runtime.low": 120,
"input.sensitivity": "medium",
"input.transfer.high": 266,
"input.transfer.low": 180,
"ups.delay.shutdown": 20
}
}
}
}
I actually power four secondary Raspberry Pi computers from this UPS device.
Each of these runs upsmon
in slave mode, hence the clients
.
Synology DSM 7.1
Synology DSM 7.1 includes a DSM-specific version of NUT. It is configured through the UPS panel in the Hardware & Power section of the Control Panel. Check Enable UPS support, chose your UPS Type (USB UPS in my case), and check by pressing Device Information that the Synology can read the UPS device.
Next, check Enable Network UPS Server.
This should add a line LISTEN=0.0.0.0
to /etc/ups/upsd.conf
, telling upsd
to accept incoming network connections.
If Homebridge UPS runs on a different server, add the IP address of that server under Permitted Synology NAS devices.
The configuration is in /etc/ups
.
It seems that ups.conf
and upsd.conf
are managed exclusively through the Control Panel; any manual edits are overwritten.
upsd.users
can be edited, configuring a username for Homebridge UPS to control the UPS:
[upsadmin]
password = secret
actions = SET
instcmds = ALL
Note that the user monuser
is used by upsmon
on the primary (master) and secondary (slave) systems powered by the UPS.
Raspberry Pi OS bullseye
Raspberry Pi OS bullseye doesn't include NUT by default, but it can be installed through sudo apt install nut
.
This should create default configuration files in /etc/nut
, install upsd
and upsc
, and corresponding man
pages.
In nut.conf
, configure NUT as standalone or primary computer, accessible over the network:
MODE=netserver
In ups.conf
, configure the UPS device:
[ups]
driver = usbhid-ups
port = auto
desc = "pi4"
In upsd.conf
, allow incoming connections to upsd
:
LISTEN 0.0.0.0
In upsd.users
, specify a upsadmin
user for Homebridge UPS:
[upsadmin]
password = secret
actions = SET
instcmds = ALL