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    adduser ampy audio  # ampy can use audio
  49    adduser www-data ampy  # httpd in group ampy
  50
  51 RRD database
  52 ------------
  53
  54 Ampy uses the Round Robin Database provided by RRDtool.
  55
  56 The database can be set up with::
  57
  58     rrdtool create /var/lib/rrdcached/db/power.rrd \
  59         --step 1s \
  60         DS:watts:GAUGE:1s:0:10000 \
  61         RRA:AVERAGE:0.5:1s:1d \
  62         RRA:AVERAGE:0.5:1m:3d \
  63         RRA:AVERAGE:0.5:15m:1w \
  64         RRA:AVERAGE:0.5:1h:30d \
  65         RRA:AVERAGE:0.5:1d:3y \
  66         RRA:MAX:0.5:1d:3y \
  67         RRA:AVERAGE:0.5:1month:10y \
  68         RRA:MAX:0.5:1month:10y
  69    chown ampy: /var/lib/rrdcached/db/power.rrd
  70    chmod 664 /var/lib/rrdcached/db/power.rrd
  71
  72
  73 rrdcached daemon helps being more efficient.
  74
  75 rrdcached socket must be available to both ampy daemon and apache.
  76
  77 Copy ``etc/rrdcached`` in ``/etc/default/rrdcached`` and adjust the ARGS parameter to match your program location.
  78
  79
  80
  81 Configuration
  82 =============
  83
  84 Select the alsa audio input
  85 ---------------------------
  86
  87 Run ``device.py`` to find out which entry you should use.
  88
  89 Then adjust DEVICE in run.py
  90
  91 A small ``record.py`` tool is available. It will give you a 50Hz .wav file with heigh proportional to your power consumption.
  92
  93 At this point, ``sudo -u ampy run.py --norecord`` should run and give you real time values.
  94
  95 Volume
  96 ------
  97
  98 Capture volume should be as high as possible, without clipping. A good value is 0 dB::
  99
 100     root:~# amixer -c 1 contents
 101     numid=23,iface=mixer,name='capture volume'
 102       ; type=integer,access=rw---r--,values=2,min=0,max=46,step=0
 103       : values=17,17
 104       | dbscale-min=-16.00db,step=1.00db,mute=0
 105
 106 In that case volume should be set to 17.
 107
 108 You can also use ``alsamixer``. The control should show ``Capture [dB gain: 0.00, 0.00]``.
 109
 110 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.
 111
 112
 113 Calibration
 114 -----------
 115
 116 You'll need to adjust VOLUME_CONSTANT in run.py so that you get the correct voltage value.
 117
 118 Autostart
 119 ---------
 120
 121 When setup is done, daemon should be started automatically, for long term statistics::
 122
 123    cp etc/init /etc/init.d/ampy
 124    update-rc.d ampy defaults
 125
 126 Apache
 127 ------
 128
 129 Just point your DocumentRoot to the ampy/html directory.
 130
 131 You should really password protect the access with something. Create a password file::
 132
 133     root:~# htpasswd /var/lib/ampy/htusers myusername
 134
 135 Then add something like that in your apache configuration file::
 136
 137    <Location />
 138        AuthType Basic
 139        AuthName "Ampy's Realm"
 140        AuthUserFile /var/lib/ampy/htusers
 141        Require valid-user
 142    </Location>
 143    # Certbot / let's encrypt challenge dir has no password:
 144    <Location /.well-known>
 145        Require all granted
 146    </Location>
 147
 148
 149 Counter initialization
 150 ----------------------
 151
 152 If you have a regular electric meter::
 153
 154    echo "123456" > /var/lib/ampy/counter
 155    chown ampy: /var/lib/ampy/counter
 156
 157
 158 Copyright
 159 =========
 160
 161 Copyright 2018-2019 Nirgal Vourgère
 162
 163 This program is free software: you can redistribute it and/or modify
 164 it under the terms of the GNU General Public License as published by
 165 the Free Software Foundation, either version 3 of the License, or
 166 (at your option) any later version.
 167
 168 This program is distributed in the hope that it will be useful,
 169 but WITHOUT ANY WARRANTY; without even the implied warranty of
 170 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 171 GNU General Public License for more details.
 172
 173 You should have received a copy of the GNU General Public License
 174 along with this program.  If not, see http://www.gnu.org/licenses/.
 175
 176
 177 Notes to cleanup (ignore that)
 178 ==============================
 179
 180 ::
 181
 182     rrdtool create power.rrd --daemon /var/run/rrdcached.sock --step 1s DS:watts:GAUGE:1:0:6600 RRA:AVERAGE:0.5:1s:1d
 183     # Buggy: nécessite des updates toutes les 500 ms
 184
 185
 186     Ceci n'est pas rafraîchi très souvent:
 187
 188     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'
 189     Alors que ça si:
 190     watch -n 0.5 rrdtool lastupdate --daemon /var/run/rrdcached.sock /var/lib/rrdcached/db/power.rrd