Enabled HTTP chunked transfer encoding
[ampy.git] / 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