Plugins/NUT UPS.html

UPS Monitoring python plugin for Domoticz

IMPORTANT NOTE: This is Beta software, so you use it at your own risk…

Version 0.1.0 (stable release, June 30 2017)

Author: Logread (aka 999LV on Github)

Plugin objective:

Expose via Domoticz devices a number of status variables reported by compatible UPS (Uninterruptible Power Supply) units via a NUT (Network UPS Tools) server running on the same local network as the Domoticz system. An example could be a UPS compatible with a Synology NAS and connected to it with UPS management enabled on the Synology NAS.

The plugin is written so as to avoid the need to install any client side software or "packet" such as the NUT Client. It fetches the UPS data directly from the NUT Server via a telnet session, updated every minute (hence any change in the UPS status such as switching to backup power may take up to one minute to be reflected. This is a compromise setting to avoid undue network traffic)

This plugin allows the monitoring/logging of the following UPS variables:

1. "ups.status": displayed as alert device "UPS Status" - the status of the UPS (Green = On Line, Red = Backup power)
2. "battery.charge": displayed as device "UPS Charge" - the % charge of the UPS battery
3. "battery.runtime": displayed as device "UPS Backup Time" - estimated time on backup power before the UPS dies
4. "input.voltage": displayed as device "UPS DC Input" - the voltage of the DC mains input
5. "ups.load": displayed as "UPS Load" - the load output in % of max power of the UPS
6. "ups.realpower": displayed as "UPS Power" - effective power in watts of the UPS load
7. "input.frequency": displayed as device "UPS DC Frequency" - the frequency of the DC mains input

Only the "UPS Status" device is always created by the plugin, others are created if the specific UPS reports the variable. Here is a screenshot with all these devices:

Prerequisites:

1. The Domoticz system on which the plugin runs must be version 3.7418 minimum (otherwise Domoticz might crash due to a bug in the python plugin framework).
2. The python plugin system must be installed (see the instructions at https://www.domoticz.com/wiki/Using_Python_plugins ).
3. A NUT server must be runnning on the same LAN as the Domoticz system on which the plugin runs. In the event the NUT server has IP clients restrictions (such as the UPS Management on Synology NAS), make sure to add the IP of the Domoticz system to the list of authorized clients.

Installation:

The below instructions are for a Raspberry Pi Linux platform… I have not tested this on other platform (e.g. Windows) but I assume a bit of search on the Domoticz forum can help you…

1. Open a shell session
2. Navigate to the directory holding your Domoticz installation (typically ~/domoticz)
3. Perform the following commands within the shell:

cd plugins
git clone https://github.com/999LV/NUT_UPS.git NUT_UPS
sudo service domoticz restart

Now connect to Domoticz with your browser and go to the “Setup/Hardware” page and select the “UPS Monitor” type from the drop-down list

1. Enter the IP address of the NUT server on your LAN (or 127.0.0.1 if the NUT server runs on the same machine as Domoticz)
2. Enter the port of the NUT server (if different from the default (3493)
3. Enter the username and password of the NUT server (if enabled). Leave blank if access control is not activated.
4. Enter the name of the relevant UPS to be monitored, as published by the NUT server (e.g. "ups" on Synology UPS Management)
5. “Add” the new hardware…

And you are done… the plugin will create serveral devices, some immediately visible in the "Utilities" tab of Domoticz, others that you will find in the “Settings/Devices” page and then can mark as used to move these to the “Utilities” page (these are marked as unused by default to avoid clutter on the Domoticz interface… See below screen shot for illustration

In case something does not work, enable the “Debug” mode for the plugin in the “Settings/Hardware” page and check the logs for errors and send me a pm @ logread on the Domoticz forum with the description of the error(s) and copy of the relevant log entries. But first please check your UPS is properly reported by the NUT Server by running the upsc command line utility in a shell session (e.g. upsc [email protected]). See http://networkupstools.org for reference on the NUT protocol and utilities.

Updating to last version:

1. Open a shell session
2. Navigate to the directory holding your Domoticz installation (typically ~/domoticz)
3. Perform the following commands within the shell:

cd plugins/NUT_UPS
git reset –-hard
git pull --force
sudo chmod +x plugin.py
sudo /etc/init.d/domoticz.sh restart