Added note about cgroup2 protection
[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 ammeter 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 select which entry you want to 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
195
196     If you want to run in a cgroup2 protected container, you need to add:
197     lxc.cgroup2.devices.allow = c 116:* rwm