Subversion Repositories rld.domoticz

# 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)

## Contents
[toc]

## 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…

![Hwscreenshot](.\afbeeldingen\Hwscreenshot.png)

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

![Hwscreenshot](.\afbeeldingen\Sensorscreenshot.png)

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).