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