PyToon Documentation Release 0.0.1 Marco Plaisier Jul 01, 2017 Contents 1 PyToon 3 1.1 PyToon measures electricity, water and gas meters and creates fancy graphs..............3 1.2 Features..................................................3 1.3 Hardware.................................................3 2 Installation 9 3 Usage 11 4 Contributing 13 4.1 Types of Contributions.......................................... 13 4.2 Get Started!................................................ 14 4.3 Pull Request Guidelines......................................... 15 4.4 Tips.................................................... 15 5 Credits 17 5.1 Development Lead............................................ 17 5.2 Contributors............................................... 17 6 History 19 6.1 0.0.1 (2014-10-01)............................................ 19 7 Indices and tables 21 i ii PyToon Documentation, Release 0.0.1 Contents: Contents 1 PyToon Documentation, Release 0.0.1 2 Contents CHAPTER 1 PyToon PyToon measures electricity, water and gas meters and creates fancy graphs PyToon measures electricity, water and gas consumption and gives you the ability to monitor your energy and water usage every second of every day. Most hardware available on the market today costs at least C 200,-. You may even need to enter into an new contract with an energy supplier. And even then it can’t even measure your water consumption! PyToon will measure your water consumption, your data is safe inside your home network, and it will only set you back C 120,- but you do need to install it yourself. • Free software: BSD license • Documentation: http://pytoon.rtfd.org. Features • Measure and view realtime electricity, gas and water consumption • Detect usual and unusual consumption patterns • Great insight into historical data • Tinkering, extend and control your setup and data • Use hardware from Tinkerforge and the Raspberry Pi foundation Hardware PyToon is based on open off-the-shelf hardware. It uses hardware from .. _Tinkerforge: http://www.tinkerforge.com/ and a .. _Raspberry Pi: http://www.raspberrypi.org/. 3 PyToon Documentation, Release 0.0.1 Raspberry Pi The Raspberry Pi is the central control unit. It analyses energy and water consumption and creates insight into your consumption patterns. Flask Flask is the web application stack used to generate the mobile website. Measurement hardware All measurement is done by bricklets from .. _Tinkerforge: http://www.tinkerforge.com/. Together with the master brick and Ethernet extension brick, the bricklets provide a robust, cheap and extensible method for creating hardware systems. Master Brick The master brick is the basis for the hardware. It has connection points for four bricklets and supplies power to the whole stack. The bricklets are connected to the master brick through 1.5m long cables. These cables are shielded, but this is not really necessary. 4 Chapter 1. PyToon PyToon Documentation, Release 0.0.1 Ethernet Extension The ethernet brick sits on top of the master brick. It is also possible to connect the master brick directly through USB with the Raspberry Pi. However, this would make programming and debugging a lot harder. With the Ethernet Extension, it is possible to connect directly to the hardware through your network. You can put the Raspberry Pi anywhere with an (wired) connection. Sensors (bricklets) The sensors are the most important part of the hardware. PyToon uses three different types, because each meter uses different indicators. For example, the gas meter uses a spinning magnet while the water meter uses a rotating reflective dial. 1.3. Hardware 5 PyToon Documentation, Release 0.0.1 Ambient Light Bricklet This was the trickiest sensor to get right. The electricity meter has a little diode or led that flashes every time a Wh is consumed. When I first installed the ambient light bricklet and used the brick viewer to test it, it didn’t seem to work consistently. The graph of the viewer sometimes didn’t show a spike when the diode flashed. After a little testing I found that the problem was not in the bricklet, but in the graph. The graph updates every half second or so. The illumination would go from 0 to 80 lux and back to zero in less time and the spikes did not show in the graph. Fortunately, the bricklet does register the brief flash. Hall Effect Bricklet The Hall Effect bricklet is used to measure gas consumption. The rotary dial in the gas meter has a magnet connect to the least significant digit. Every revolution this magnet passes the bricklet and thanks to the .. _Hall effect: http://en.wikipedia.org/wiki/Hall_effect it is possible to measure each revolution 6 Chapter 1. PyToon PyToon Documentation, Release 0.0.1 Line Bricklet The water meter has a little rotating dial that is partly reflective. A line bricklet is used to detect whether the dial is rotating or not. 1.3. Hardware 7 PyToon Documentation, Release 0.0.1 8 Chapter 1. PyToon CHAPTER 2 Installation At the command line: $ easy_install pytoon Or, if you have virtualenvwrapper installed: $ mkvirtualenv pytoon $ pip install pytoon 9 PyToon Documentation, Release 0.0.1 10 Chapter 2. Installation CHAPTER 3 Usage To use PyToon in a project: import pytoon 11 PyToon Documentation, Release 0.0.1 12 Chapter 3. Usage CHAPTER 4 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: Types of Contributions Report Bugs Report bugs at https://github.com/marcofinalist/pytoon/issues. If you are reporting a bug, please include: • Your operating system name and version. • Any details about your local setup that might be helpful in troubleshooting. • Detailed steps to reproduce the bug. Fix Bugs Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it. Implement Features Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it. 13 PyToon Documentation, Release 0.0.1 Write Documentation PyToon could always use more documentation, whether as part of the official PyToon docs, in docstrings, or even on the web in blog posts, articles, and such. Submit Feedback The best way to send feedback is to file an issue at https://github.com/marcofinalist/pytoon/issues. If you are proposing a feature: • Explain in detail how it would work. • Keep the scope as narrow as possible, to make it easier to implement. • Remember that this is a volunteer-driven project, and that contributions are welcome :) Get Started! Ready to contribute? Here’s how to set up pytoon for local development. 1. Fork the pytoon repo on GitHub. 2. Clone your fork locally: $ git clone [email protected]:your_name_here/pytoon.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv pytoon $ cd pytoon/ $ python setup.py develop 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 pytoon tests $ python setup.py test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. 14 Chapter 4. Contributing PyToon Documentation, Release 0.0.1 Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/ marcofinalist/pytoon/pull_requests and make sure that the tests pass for all supported Python versions. Tips To run a subset of tests: $ python -m unittest tests.test_pytoon 4.3. Pull Request Guidelines 15 PyToon Documentation, Release 0.0.1 16 Chapter 4. Contributing CHAPTER 5 Credits Development Lead • Marco Plaisier <[email protected]> Contributors None yet. Why not be the first? 17 PyToon Documentation, Release 0.0.1 18 Chapter 5. Credits CHAPTER 6 History 0.0.1 (2014-10-01) • First release on PyPI. 19 PyToon Documentation, Release 0.0.1 20 Chapter 6. History CHAPTER 7 Indices and tables • genindex • modindex • search 21.