j4ym0 / pyenergenie

A python interface to the Energenie line of products

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

Purpose

This is an early release, and is the beginnings of this work. It is not representative of the final API, but it is a starting point for me to start experimenting with ideas and testing out reliability.

With it, you can receive monitor payloads from an Energenie MiHome Adaptor Plus, directly within Python programs. This type of plug can be used for energy monitoring and also for relay control of the socket.

You can also turn switches on MiHome Adaptor Plus on and off.

There is now also support for the legacy green-button switch devices ENER002, which you can access from the legacy.py program.

Work is ongoing to build up the higher layers of this software, so that devices from the MiHome (MIHO) and ENER ranges can be used interchangeably. Please look at the issues log to see how this work is progressing.

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 and PiZero. There is no reason why it should not work on the A and A+ but I haven't tested those combinations yet.

2. Use the Download As Zip link to the right of this page

3. unzip the software

unzip pyenergenie-master.zip
cd pyenergenie-master
cd src

4. run the monitor test program with your MiHome adaptors

sudo python monitor.py

After a few seconds, you should see some packet dumps appearing on the screen. These packets are then decoded and displayed in a dictionary format, and for certain messages, also in a more friendly format.

5. run the switch test program with MiHome control adaptors

sudo python switch.py

This will listen for any MiHome adaptor plus devices, and then turn their switch on and off every 10 seconds.

6. Run the legacy device support program with your green button devices

sudo python legacy.py

Note that the protocol module (OpenThings) is completely generic and will pretty much work with any device. Try plugging in an E-TRV and see what messages get reported. Construct new template messages as pydict initialisers and encode and send those in to make the device do something in response.

Experimental

You can try combined.py which is an example of how to switch both the purple MiHome plugs, and the green button legacy plugs in the same application (at the moment you have to use the unified_radio branch to do this, as I haven't merged this to master), but I tried it here and it works.

Plans

1. Build a device-agnostic interface so that any device can be registered with a friendly name, and then controlled with helpful commands like

tv.turn_on()
p = tv.get_power()

whaleygeek#18

2. Write a message scheduler, so that transmits only occur in safe timeslots that are less likely to collide with transmits from devices (and thus increase reliability of messaging in a large device installation)

whaleygeek#9

3. Write javascript NodeRed wrappers around the Python (like GPIO nodes do) so that you can drop NodeRed nodes for Energenie devices into a flow.

whaleygeek#38

David Whale

@whaleygeek

May 2016