Documentation
[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 * 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