Skip to content

Homebridge plugin for NUT (Network UPS Tools) Client

Notifications You must be signed in to change notification settings

vectronic/homebridge-nut

 
 

Repository files navigation

homebridge-nut

A NUT (Network UPS Tools) Plugin for Homebridge leveraging node-nut.

This plugin allows you to monitor multiple UPS devices with HomeKit via a NUT Client.

NOTE: This is re-write of https://github.com/ToddGreenfield/homebridge-nut to avoid usage of system-sleep and deasync module dependencies which end up relying on native code. I was having problems with these blocking the Node event loop (possibly due to running on FreeBSD). I also wanted to avoid the need of having to do native code rebuilds...

Installation

  1. Install Homebridge using: npm install -g homebridge
  2. Install this plugin using: npm install -g @vectronic/homebridge-nut
  3. Update your configuration file. See a sample config.json snippet below.
  4. Ensure you have a NUT Client running somewhere.

This plugin will create an accessory for each UPS returned from the NUT Client.

The accessory will have a ContactSensor service and a BatteryService.

The ContactSensor will have the following characteristics:

  • ContactSensorState will be open if UPS Status starts with OB (On Battery).
  • StatusActive will be true if UPS Load is greater than 0.
  • StatusFault will be true if NUT is not reachable.

The BatteryService will have the following characteristics:

  • BatteryLevel will show the battery charge percentage.
  • ChargingState will show Charging, Not Charging (online and 100% battery charge), or Not Chargeable (on battery).
  • StatusLowBattery will be true if BatteryLevel is below low_batt_threshold.

Configuration

Example config.json entry:

"platforms": [
  {
    "platform": "Nut",
    "name": "Nut",
    "host": "localhost",
    "port": 3493,
    "username": "foo",
    "password": "bar",
    "low_batt_threshold": 40,
    "poll_interval": 60,
    "connect_interval": 5,
    "command_interval": 1,
    "ups_key_excludes": [
        "foo",
        "bar"
    ],
    "disable_battery_service": false
  }
]

Where the following properties are all optional:

  • name is the name used for Homebridge logging. Default is Nut.
  • host is the IP or hostname for the Nut Client. Default is localhost.
  • port is the port for the Nut Client. Default is 3493.
  • username is the username to use for Nut Client authentication.
  • password is the password to use for Nut Client authentication.
  • low_batt_threshold is the battery level percentage at which to set the Low Battery Status to true. Default is 40.
  • poll_interval is the UPS polling interval in seconds. Default is 60.
  • connect_interval is the NUT client connection attempt interval in seconds. Default is 5.
  • command_interval is the NUT client delay interval between success requests in seconds. Default is 1.
  • ups_key_excludes is a list of Nut configured UPS keys which should be ignored.
  • disable_battery_service is optional and should almost always be false which is the default. In rare circumstances where your UPS is not fully supported by NUT you may wish to disable this.

Help etc.

If you have a query or problem, raise an issue in GitHub, or better yet submit a PR!

About

Homebridge plugin for NUT (Network UPS Tools) Client

Topics

Resources

Stars

Watchers

Forks

Sponsor this project

 

Languages

  • TypeScript 100.0%