Documentation
authorNirgal <contact_ampy@nirgal.com>
Sun, 13 Oct 2019 10:25:45 +0000 (10:25 +0000)
committerNirgal <contact_ampy@nirgal.com>
Sun, 13 Oct 2019 10:25:45 +0000 (10:25 +0000)
Removed some hardcoded file locations

README.rst
countercron
html/ampy.php
html/currentjson_chunked.php
html/lastupdate.php

index c6e19ae7c384cbf2461df2ca51d42f4a71a3a76c..5bddf100c65bc8b00f137d743494e07caeb8dc91 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,30 @@ 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
+* 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 +47,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 +68,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 +106,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 +117,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 +148,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)
 ==============================
 
index ec964da1f8f983f797455f06269ef2568f9634fe..6a5ccb59fec6234bc875c2b6da7e10111123a7e5 100755 (executable)
@@ -1,5 +1,11 @@
 #!/usr/bin/php -f
 <?php
+/*
+ * This scripts updates the "counter" file based on average consumption and
+ * last known value.
+ *
+ * It is not used!
+ */
 include("html/config.php");
 
 exec("/usr/bin/rrdtool flushcached --daemon ".RRDSOCK." ".RRDFILE);
index 991ca6734700172859377d979fc12031331b38d1..88638c4b9543c313ceb3728ab11ba58b3558bf97 100644 (file)
@@ -1,4 +1,7 @@
 <?php
+/*
+ * This file is not used!
+ */
 $RRDFILE='/home/nirgal/ampy/power.rrd';
 $COUNTERFILE='/home/nirgal/ampy/counter';
 
index 34f5c8b059c54ae85abc2af84298de8e8ba38ea3..a860df51b596268dc1bb6083d1189a5c94c6c837 100644 (file)
@@ -1,5 +1,11 @@
 <?php
-$RRDFILE="/home/nirgal/ampy/power.rrd";
+/*
+ * Experimental version that return chunked http response.
+ *
+ * Pulling the values is no longer needed as the one request will output
+ * the updates every 10 seconds.
+ */
+require_once('config.php');
 
 header("Content-Type: text/json");
 header("Transfer-Encoding: chunked");
@@ -17,11 +23,12 @@ function send_chunk($chunk)
 }
 
 while (True) {
-       $info=rrd_lastupdate($RRDFILE);
+       $info=rrd_lastupdate(RRDFILE);
        if ($info === FALSE)
                $result=[
                        'last_update' => 'unknown',
-                       'watts' => 'unknown'
+                       'watts' => 'unknown',
+                       'error' => rrd_error(),
                ];
        else
                $result=[
index 980a11e556a98294357f297f39e52d58aaab7dbf..74a9479d345d4dbc61d729cf79a9b7cc5da0f456 100644 (file)
@@ -2,11 +2,11 @@
 <meta charset="UTF-8">
 
 <?php
-$RRDFILE="/home/nirgal/ampy/power.rrd";
+require_once('config.php');
 
-$info=rrd_lastupdate($RRDFILE);
+$info=rrd_lastupdate(RRDFILE);
 if ($info === FALSE)
-       echo("error in rrd_lastupdate");
+       echo("error in rrd_lastupdate: ".rrd_error());
 else
        print_r($info);
 ?>