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