Fork: 0
alex / pyenergenie
Transfer to URL with SHA Find file
Newer
Older
pyenergenie / README.md
@David Whale David Whale on 30 May 2016 5 KB Now runs on Raspberry Pi 3 also
Raw Blame History

pyenergenie

A python interface to the Energenie line of products

https://energenie4u.co.uk/

Energenie devices (both the green button devices, and the newer MiHome range) can be controlled and monitored by this Python library on a Raspberry Pi. With it you can turn sockets on and off, and monitor energy usage.

There are two ways to control Energenie devices from a Raspberry Pi. One of their boards maps 4 GPIO's to transmit 4 standard messages. For that board, use this code from Ben Nuttall and Amy Mather: https://pypi.python.org/pypi/energenie

The second board, the ENER314-RT board, is a full radio that is programmable from the SPI interface of the Raspberry Pi. For that board, please use this code, which now supports all models of Raspberry Pi, and all devices from Energenie (including the old green button devices and the new MiHome monitor devices).

The Energenie product line uses the HopeRF radio transciever, and the OpenThings protocol from Sentec. Energenie have built a RaspberryPi add-on board that interfaces to the HopeRF RFM69, and allows both control and monitoring of their products from a Raspberry Pi.

Energenie have some (old) sample code written in C to control and monitor their devices, but this package is now considered to be far superior. Energenie have been very kind in supporting this work by loaning devices to help with the testing of this code.

This python library uses a 'zero install' strategy, by embedding everything that is needed in once place. In theory, you can just press the DownloadZip button, unzip the code, and run it, and it will work. (None of that sudo apt-get install nonsense!)

This code should work with both Python 2 and Python 3. It has been tested with both, but note that ongoing development occurs in Python 2, and the Python 3 compatibility is only re-tested at each major release.

Purpose

This library of code is designed to be everything you need to get going with writing a fully functional application for the Energenie devices (both monitoring and control).

Getting Going

  1. Plug in your ENER314-RT-VER01 board from Energenie onto the 26 pin or 40 pin connector of your Raspberry Pi. This is tested on Raspberry Pi B, B+ B2 and 2B, 3 and PiZero. There is no reason why it should not work on the A and A+ but it hasn't been specially tested on those combinations yet.

  2. Press the CLONE OR DOWNLOAD button to the right of this page, and choose the DOWNLOAD ZIP option.

  3. unzip the software (from a terminal prompt, e.g. LXTermina)

unzip pyenergenie-master.zip
cd pyenergenie-master
cd src
  1. If you have legacy green button devices, run the setup_tool to learn those devices to your code
sudo python setup_tool.py
option 1. legacy learn mode
ENTER for default house code (or type in a hex number with 5 digits like 12345 or CAB12)
ENTER for switch 1 (or choose 1,2,3,4)

Hold the green button on your legacy device until it starts to flash. It should then learn the house code being broadcast by the setup tool, and then start switching on and off.

You can edit the registry.kvs to ADD a record for an ENER002 to give this device a friendly name - look at the examples already in the file.

If you know the house code assigned to an RF hand controller, you can program that into your code (and your registry.kvs) to make the socket work with both. (Note: I will be adding a learn mode for RF hand remotes in a later release, you can't learn their codes yet without having special diagnostics equipment to hand).

  1. If you have a MiHome device, run the setup_tool to learn those devices
sudo python setup_tool.py
option 2. mihome discovery mode

Wait for data to arrive from your mihome device (every 10 seconds) and accept it when it says 'remember device' - the device is now in the registry.kvs file and can be used in all other demo programs easily.

  1. Try the other demo programs, the simplest one to start using and modifying is control_any_auto.py as it shows how to refer to devices in your registry by a simple variable name, and you can switch them on and off in a device agnostic way (all switchable devices have a turn_on and turn_off function). This is probably the best way to write your app, by learning your devices into the registry (or hand coding them in there) and then just referring to them by name in your python program.
  1. Try the other demo programs

These other python programs show off some other features of the Energenie Python library:

control_any_auto.py       auto variable creation from your registry.kvs
control_any_noreg.py      creating your variables manually without a registry
control_any_reg.py        control all switchable devices regardless of name, from registry
discover_mihome.py        a discovery example, there are 4 standard discovery behaviours
mihome_energy_monitor.py  a simple logger that logs all energy messages to energenie.csv
  1. Future work

For details about future plans and work, please see the github issues log here:

https://github.com/whaleygeek/pyenergenie/issues

David Whale

@whaleygeek

May 2016