README.rst

   1 ===========================================
   2 Ampy - The spying meter that doesn't snitch
   3 ===========================================
   4
   5 Ampy is a tool to monitor your power consumption.
   6
   7 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.
   8
   9 .. contents::
  10
  11 Hardware
  12 ========
  13
  14 You need a ampmeter sensor that outputs an audio signal.
  15
  16 It has been tested with `this YHDC sensor`_.
  17
  18 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.
  19
  20 **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.
  21
  22 .. _`this YHDC sensor`: https://learn.openenergymonitor.org/electricity-monitoring/ct-sensors/yhdc-sct-013-000-ct-sensor-report
  23
  24
  25
  26 Sofware installation
  27 ====================
  28
  29 Dependencies
  30 ------------
  31
  32 * apache2
  33 * libapache2-mod-php | php-cgi | php-fpm
  34 * libjs-jquery
  35 * php-rrd
  36 * python3-pyaudio
  37 * python3-rrdtool
  38 * rrdcached
  39 * ...
  40
  41 User setup and permissions
  42 --------------------------
  43
  44 Ampy requires permission to use the sound card. It's recommanded to create a dedicated user::
  45
  46    addgroup --system ampy  # create a dedicated group
  47    adduser --system --ingroup ampy --home /var/lib/ampy --disabled-password --disabled-login ampy
  48    chmod g+ws /var/lib/ampy/  # group can write, sticky group
  49    adduser ampy audio  # ampy can use audio
  50    adduser www-data ampy  # httpd in group ampy
  51
  52 RRD database
  53 ------------
  54
  55 Ampy uses the Round Robin Database provided by RRDtool.
  56
  57 The database can be set up with::
  58
  59     rrdtool create /var/lib/rrdcached/db/power.rrd \
  60         --step 1s \
  61         DS:watts:GAUGE:1s:0:10000 \
  62         RRA:AVERAGE:0.5:1s:1d \
  63         RRA:AVERAGE:0.5:1m:3d \
  64         RRA:AVERAGE:0.5:15m:1w \
  65         RRA:AVERAGE:0.5:1h:30d \
  66         RRA:AVERAGE:0.5:1d:3y \
  67         RRA:MAX:0.5:1d:3y \
  68         RRA:AVERAGE:0.5:1month:10y \
  69         RRA:MAX:0.5:1month:10y
  70    chown ampy: /var/lib/rrdcached/db/power.rrd
  71    chmod 664 /var/lib/rrdcached/db/power.rrd
  72
  73
  74 rrdcached daemon helps being more efficient.
  75
  76 rrdcached socket must be available to both ampy daemon and apache.
  77
  78 Copy ``etc/rrdcached`` in ``/etc/default/rrdcached`` and adjust the ARGS parameter to match your program location.
  79
  80
  81
  82 Configuration
  83 =============
  84
  85 Select the alsa audio input
  86 ---------------------------
  87
  88 Run ``device.py`` to find out which entry you should use.
  89
  90 Then adjust DEVICE in run.py
  91
  92 A small ``record.py`` tool is available. It will give you a 50Hz .wav file with heigh proportional to your power consumption.
  93
  94 At this point, ``sudo -u ampy run.py --norecord`` should run and give you real time values.
  95
  96 Volume
  97 ------
  98
  99 Capture volume should be as high as possible, without clipping. A good value is 0 dB::
 100
 101     root:~# amixer -c 1 contents
 102     numid=23,iface=mixer,name='capture volume'
 103       ; type=integer,access=rw---r--,values=2,min=0,max=46,step=0
 104       : values=17,17
 105       | dbscale-min=-16.00db,step=1.00db,mute=0
 106
 107 In that case volume should be set to 17.
 108
 109 You can also use ``alsamixer``. The control should show ``Capture [dB gain: 0.00, 0.00]``.
 110
 111 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.
 112
 113
 114 Calibration
 115 -----------
 116
 117 You'll need to adjust VOLUME_CONSTANT in run.py so that you get the correct voltage value.
 118
 119 Starting and stoping a powerfull apliance you know the consuptium of, should give you a good start.
 120
 121 Later on, you can adjust the value based on your legal counter. See bellow.
 122
 123 Autostart
 124 ---------
 125
 126 When setup is done, daemon should be started automatically, for long term statistics::
 127
 128    cp etc/init /etc/init.d/ampy
 129    update-rc.d ampy defaults
 130
 131 Apache
 132 ------
 133
 134 Just point your DocumentRoot to the ampy/html directory.
 135
 136 You should really password protect the access with something. Create a password file::
 137
 138     root:~# htpasswd /var/lib/ampy/htusers myusername
 139
 140 Then add something like that in your apache configuration file::
 141
 142    <Location />
 143        AuthType Basic
 144        AuthName "Ampy's Realm"
 145        AuthUserFile /var/lib/ampy/htusers
 146        Require valid-user
 147    </Location>
 148    # Certbot / let's encrypt challenge dir has no password:
 149    <Location /.well-known>
 150        Require all granted
 151    </Location>
 152
 153
 154 Counter initialization
 155 ----------------------
 156
 157 Point your browser to counterset.php.
 158
 159 You should do that from time to time. It will show you how off the system is. You can then adjust your VOLUME_CONSTANT in run.py.
 160
 161
 162 Copyright
 163 =========
 164
 165 Copyright 2018-2019 Nirgal Vourgère
 166
 167 This program is free software: you can redistribute it and/or modify
 168 it under the terms of the GNU General Public License as published by
 169 the Free Software Foundation, either version 3 of the License, or
 170 (at your option) any later version.
 171
 172 This program is distributed in the hope that it will be useful,
 173 but WITHOUT ANY WARRANTY; without even the implied warranty of
 174 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 175 GNU General Public License for more details.
 176
 177 You should have received a copy of the GNU General Public License
 178 along with this program.  If not, see http://www.gnu.org/licenses/.
 179
 180
 181 Notes to cleanup (ignore that)
 182 ==============================
 183
 184 ::
 185
 186     rrdtool create power.rrd --daemon /var/run/rrdcached.sock --step 1s DS:watts:GAUGE:1:0:6600 RRA:AVERAGE:0.5:1s:1d
 187     # Buggy: nécessite des updates toutes les 500 ms
 188
 189
 190     Ceci n'est pas rafraîchi très souvent:
 191
 192     watch -n 0.5 rrdtool graphv - '-s' '1546280606' 'DEF:watts=/var/lib/rrdcached/db/power.rrd:watts:AVERAGE' 'VDEF:avg=watts,AVERAGE' 'VDEF:last=watts,LAST' 'PRINT:avg:%lf' 'PRINT:last:%lf'
 193     Alors que ça si:
 194     watch -n 0.5 rrdtool lastupdate --daemon /var/run/rrdcached.sock /var/lib/rrdcached/db/power.rrd