diff --git a/README.md b/README.md index 460d01c..6d8c7fe 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ 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. +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. @@ -34,26 +34,17 @@ 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 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. +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 @@ -61,12 +52,13 @@ 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. +no reason why it should not work on the A and A+ but it hasn't been specially tested on +those combinations yet. -2. Use the Download As Zip link to the right of this page +2. Press the CLONE OR DOWNLOAD button to the right of this page, and choose the +DOWNLOAD ZIP option. -3. unzip the software +3. unzip the software (from a terminal prompt, e.g. LXTermina) ``` unzip pyenergenie-master.zip @@ -74,73 +66,70 @@ cd src ``` -4. run the monitor test program with your MiHome adaptors +4. If you have legacy green button devices, run the setup_tool to learn those devices +to your code + ``` -sudo python monitor.py +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) ``` -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. +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. -5. run the switch test program with MiHome control adaptors +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). + + +5. If you have a MiHome device, run the setup_tool to learn those devices + ``` -sudo python switch.py +sudo python setup_tool.py +option 2. mihome discovery mode ``` -This will listen for any MiHome adaptor plus devices, and then turn their -switch on and off every 10 seconds. +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. -6. Run the legacy device support program with your green button devices + +6. 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. + + +7. Try the other demo programs + +These other python programs show off some other features of the Energenie Python +library: ``` -sudo python legacy.py +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 ``` +8. Future work -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. +For details about future plans and work, please see the github issues log here: - -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() -``` - -https://github.com/whaleygeek/pyenergenie/issues/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) - -https://github.com/whaleygeek/pyenergenie/issues/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. - -https://github.com/whaleygeek/pyenergenie/issues/38 +https://github.com/whaleygeek/pyenergenie/issues David Whale