More tests on http chuncked transfer
[ampy.git] / README.rst
index c6e19ae7c384cbf2461df2ca51d42f4a71a3a76c..fd1f1c201c2ca3148e9e947bf0dc0f43d1a46166 100644 (file)
@@ -2,6 +2,11 @@
 Ampy - The spying meter that doesn't snitch
 ===========================================
 
+Ampy is a tool to monitor your power consumption.
+
+It is designed for self-hosting, without any third party analysing when you're home, when you wake up or what you are doing now.
+
+.. contents::
 
 Hardware
 ========
@@ -10,29 +15,31 @@ You need a ampmeter sensor that outputs an audio signal.
 
 It has been tested with `this YHDC sensor`_.
 
-Installation is simple: You clip the sensor on the electrical line you want to mesure on one side. On the other side, you plug the jack in your sound card.
+Installation is simple: You clip the sensor on the electrical line you want to measure on one side. On the other side, you plug the jack in your sound card.
 
-DISCLAMER: You should check your sound card can handle the voltage.
+**DISCLAMER**: You should check your sound card can handle the voltage. For example, my sensor maximum output is 1 volt, which is acceptable for the "mic" input of my sound card, but not for its "line in" input which is limited to 100mV. Nowadays, sound card are quite robust: I also tried the "line in" and it didn't fried the sound chip, but I strongly advise against you trying that. Don't blame me. Check the documentation of your hardware first.
 
 .. _`this YHDC sensor`: https://learn.openenergymonitor.org/electricity-monitoring/ct-sensors/yhdc-sct-013-000-ct-sensor-report
 
 
+
+Sofware installation
+====================
+
 Dependencies
-============
+------------
 
 * apache2
 * libapache2-mod-php | php-cgi | php-fpm
+* libjs-jquery
+* php-rrd
 * python3-pyaudio
 * python3-rrdtool
 * rrdcached
 * ...
 
-
-Setup
-=====
-
-User setup
-----------
+User setup and permissions
+--------------------------
 
 Ampy requires permission to use the sound card. It's recommanded to create a dedicated user::
 
@@ -41,13 +48,12 @@ Ampy requires permission to use the sound card. It's recommanded to create a ded
    adduser ampy audio  # ampy can use audio
    adduser www-data ampy  # httpd in group ampy
 
-
-RRD database creation
----------------------
+RRD database
+------------
 
 Ampy uses the Round Robin Database provided by RRDtool.
 
-::
+The database can be set up with::
 
     rrdtool create /var/lib/rrdcached/db/power.rrd \
         --step 1s \
@@ -63,6 +69,29 @@ Ampy uses the Round Robin Database provided by RRDtool.
    chown ampy: /var/lib/rrdcached/db/power.rrd
    chmod 664 /var/lib/rrdcached/db/power.rrd
 
+
+rrdcached daemon helps being more efficient.
+
+rrdcached socket must be available to both ampy daemon and apache.
+
+Copy ``etc/rrdcached`` in ``/etc/default/rrdcached`` and adjust the ARGS parameter to match your program location.
+
+
+
+Configuration
+=============
+
+Select the alsa audio input
+---------------------------
+
+Run ``device.py`` to find out which entry you should use.
+
+Then adjust DEVICE in run.py
+
+A small ``record.py`` tool is available. It will give you a 50Hz .wav file with heigh proportional to your power consumption.
+
+At this point, ``sudo -u ampy run.py --norecord`` should run and give you real time values.
+
 Volume
 ------
 
@@ -78,23 +107,8 @@ In that case volume should be set to 17.
 
 You can also use ``alsamixer``. The control should show ``Capture [dB gain: 0.00, 0.00]``.
 
+You should disable any *mic boost*. Set it to zero. Ampy likes to have the pure signal, with a simple exponential decibel scale, without any extra low volume super boost.
 
-rrdcached setup
----------------
-
-rrdcached socket must be available to both ampy daemon and apache.
-
-See/copy ``etc/rrdcached`` in ``/etc/default/rrdcached``.
-
-
-Select the audio input
-----------------------
-
-Run device.py to find out which entry you should use.
-
-Then adjust DEVICE in run.py
-
-At this point, ``sudo -u ampy run.py --norecord`` should run and give you a value.
 
 Calibration
 -----------
@@ -104,8 +118,9 @@ You'll need to adjust VOLUME_CONSTANT in run.py so that you get the correct volt
 Autostart
 ---------
 
-::
-   ln -s /home/nirgal/ampy/etc/init /etc/init.d/ampy
+When setup is done, daemon should be started automatically, for long term statistics::
+
+   cp etc/init /etc/init.d/ampy
    update-rc.d ampy defaults
 
 Apache
@@ -134,11 +149,31 @@ Then add something like that in your apache configuration file::
 Counter initialization
 ----------------------
 
-If you have a relugar electric meter::
+If you have a regular electric meter::
 
    echo "123456" > /var/lib/ampy/counter
    chown ampy: /var/lib/ampy/counter
 
+
+Copyright
+=========
+
+Copyright 2018-2019 Nirgal Vourgère
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see http://www.gnu.org/licenses/.
+
+
 Notes to cleanup (ignore that)
 ==============================