Z-Wave BatteryLevel plugin

BatteryLevel python plugin for Domoticz

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

Version 0.6.0 (implements compatibility with OpenZwave 1.6)

Author: Logread (aka 999LV on Github)

Plugin objective:

Domoticz reports level of batteries of battery powered z-wave devices in a way that I do not find easy to use for the following reasons:

1. Battery levels are only shown in the “Setup/Devices” page and for zwave nodes that produce multiple devices, the same information is reported across all these devices.
2. The system wide “Battery Low Level” notification system within Domoticz (in “Setup/Settings/Other”) does not allow for different levels of trigger depending on devices, while it is my experience that some devices can operate for long with say 20% of battery level, while others will shortly stop after reporting a battery level of 50%.
3. The evolution of battery level over time cannot be logged for analysis of battery life patterns per devices

This plugin addresses the above as follows:

1. It polls at regular intervals the Domoticz system for z-wave nodes and creates/updates a Domoticz device for each z-wave node to show the node’s battery level
2. Each of the devices representing a battery operated z-wave node will allow:
   1. An easy to read display of the current battery level
   2. Logging over time like for any Domoticz sensor
   3. The definition of custom battery level notifications or events for each specific z-wave node
   4. As a bonus, a dynamic icon will display the battery level in 4 colors (green if >75%, yellow if 50 to 75%, orange if 25 to 50% and red if below 25%). Icons are from https://wpclipart.com/index.html , many thanks to them for these public domain graphics.

Prerequisites:

1. The Domoticz system on which the plugin runs must be version 4.11253 minimum (otherwise please use the legacy plugin «plugin legacy OZW 1.4 version.py» and rename it «plugin.pi»).
2. The python plugin system must be installed (see the instructions at https://www.domoticz.com/wiki/Using_Python_plugins ).

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
mkdir BatteryLevel
sudo apt-get update
sudo apt-get install git
git clone https://github.com/999LV/BatteryLevel.git BatteryLevel
cd BatteryLevel
sudo chmod +x plugin.py
sudo /etc/init.d/domoticz.sh restart

Now connect to Domoticz with your browser and go to the “Setup/Hardware” page and select the “Battery monitoring for Z-Wave nodes” type from the drop-down list

1. Enter the domoticz ip/port and authentication as needed (new in version 0.6.0)
2. Adjust the trigger levels for the icons if needed
3. Adjust the polling interval to your needs. The default value is 60 minutes, which matches the default “sensor expired” timing in Domoticz (setting a polling interval longer than the “sensor expired” delay will cause the battery level sensor devices to be displayed in red at times)
4. Enter the hardware idx number of your zwave controller (entering an invalid number may result in a Domoticz crash... be careful)
5. “Add” the new hardware…

And you are done… the plugin will create one device per z-wave node found, that you will find in the “Settings/Devices” page and then mark as used to move these to the “Utilities” page… See below screen shot for illustration

Important note for versions 0.6.0 or higher: upon Domoticz start up, the battery levels will only be updated when the zwave nodes wake up to send the battery level data to Domoticz and this may take a while depending on the parameters of the zwave device. During that time, the relevant plugin device will be either marked as timed out (red banner in the GUI) or not created if this is a new install. Be patient as it may take several hours for all the nodes to send their data to the controller !

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

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/BatteryLevel
git reset –-hard
git pull --force
sudo chmod +x plugin.py
sudo /etc/init.d/domoticz.sh restart

Please note version 0.6.0 has breaking changes in the parameters section, so the plugin will only be functional if you immediately edit the new parameters in the hardware section.

Known limitations:

1. The node name in the openzwave is truncated at 15 characters max. If needed, you can manually edit the corresponding device name in the Domoticz interface.
2. It is possible that the node name you gave at the time of including a z-wave device in Domoticz is not properly registered in the openzwave configuration file. If this happens, the corresponding plugin device will default to the node number).