diff --git a/README.md b/README.md index 10bad6d..e8c76c4 100644 --- a/README.md +++ b/README.md @@ -3,33 +3,14 @@ https://energenie4u.co.uk/ -Note -==== -This is the beginnings of an open source library to access the Energenie -range of power control and monitoring products from within Python. +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. -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. - -There are some existing Python libraries for some Energenie products, but they -do not support the full radio interface and full product range. - -Energenie also have a modified set of C test code based on the HopeRF test harness, -but this does not support all products, all variants of Raspberry Pi hardware, -or all versions of the Raspbian OS, unless you bring in later versions of -the BCM module to support the new device tree on the BCM2836. - -This project aims to develop an open source Python module, providing -access to many or all of the features of the OpenHEMS, HopeRF and Energenie -product line. - - -Note that there are two ways to control Energenie's from a Raspberry Pi. -One of the boards maps 4 GPIO's to transmit 4 standard messages. -For that board, use this code from Ben and Amy: +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 @@ -38,6 +19,21 @@ 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 ==== @@ -52,27 +48,23 @@ You can also turn switches on MiHome Adaptor Plus on and off. -There is support for the legacy green-button switch devices ENER002, -but it is not yet fully tested, and not integrated into the main application -flow yet - it is a separate test program legacy.py. +There is now also support for the legacy green-button switch devices ENER002, +which you can access from the legacy.py program. -I've tried to make this a 'zero install' and 'zero configuration' experience. -In theory (at least) you should be able to download the zip or git-clone, -plug in your Energenie radio, plug in your MiHome Adapter Plus, and run the code -to see data coming back. +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 connector of -your Raspberry Pi. At the moment I have only tested this with a Raspberry Pi B, -although there is no reason why it should not work with any of the models currently -available on the market. The underlying GPIO and SPI has been tested in other -projects on a Pi2 for example. +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, and unzip the files onto your -Raspberry Pi. +2. Use the Download As Zip link to the right of this page 3. unzip the software @@ -101,15 +93,12 @@ This will listen for any MiHome adaptor plus devices, and then turn their switch on and off every 10 seconds. -6. Try the legacy device support with your green button devices +6. Run the legacy device support program with your green button devices ``` sudo python legacy.py ``` -At the moment, this just switches socket 1 on and off repeatedly, -but there are other test modes in the software. - 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 @@ -120,10 +109,15 @@ Plans ==== -1. Finish off support for the legacy green-button devices. -(This is nearly completed) +1. Build a device-agnostic interface so that any device can be registered +with a friendly name, and then controlled with helpful commands like -https://github.com/whaleygeek/pyenergenie/issues/32 +``` +tv.turn_on() +p = tv.get_power() +``` + +https://github.com/whaleygeek/pyenergenie/issues/18 2. Write a message scheduler, so that transmits only occur in safe @@ -132,20 +126,15 @@ https://github.com/whaleygeek/pyenergenie/issues/9 -3. Write a Python object interface for devices - i.e. one object per -physical device on the network, with a method for each feature of that -device. This will allow very high level object oriented access to a set of -devices in an installation, in a very expressive and easy to use manner. -https://github.com/whaleygeek/pyenergenie/issues/18 - -4. Write javascript NodeRed wrappers around the Python (like GPIO nodes do) +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. https://github.com/whaleygeek/pyenergenie/issues/38 + David Whale @whaleygeek -April 2016 +May 2016