From Domoticz
Jump to: navigation, search

BatteryLevel python plugin for Domoticz

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

Version 0.4.0 (major rewrite, May 18 2017)

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 a given Domoticz system (it can be the system on which the plugin is running, but also another one in the same local network) 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 , many thanks to them for these public domain graphics.


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


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 BatteryLevel
cd BatteryLevel
sudo chmod +x
sudo /etc/init.d/ 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. 5. 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)
  2. “Add” the new hardware…

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


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

If you are updating from version 0.3.x to a newer version you will have to go to the Settings/Hardware tab in Domoticz to validate the polling interval parameter of your choice.

Under the hood – How this works

While versions prior to 0.4.0 used to rely on the Domoticz http API to fetch data, newer versions bypass Domoticz and access openzwave data directly through the “domoticz/Config/zwcfg_0x????????.xml” file (where ???????? is the controller homeid). That file holds all the current setup data of openzwave for all the nodes on the z-wave network (it is refreshed each time the openzwave configuration changes or at least once per hour). The plugin will extract BATTERY_LEVEL z-wave command class data for all nodes that report it.

Note that the plugin will skip any “domoticz/Config/zwcfg_0x????????.xml” file that has not been updated in the last two hours before startup to avoid using data from any controller that probably was removed from the system. Only one “active” controller is allowed… others will be discarded.

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, you need to “refresh” the device name in the Setup/Hardware/OpenZWave USB/Nodes list and restart Domoticz.