c6e19ae7c384cbf2461df2ca51d42f4a71a3a76c
[ampy.git] / README.rst
1 ===========================================
2 Ampy - The spying meter that doesn't snitch
3 ===========================================
4
5
6 Hardware
7 ========
8
9 You need a ampmeter sensor that outputs an audio signal.
10
11 It has been tested with `this YHDC sensor`_.
12
13 Installation is simple: You clip the sensor on the electrical line you want to mesure on one side. On the other side, you plug the jack in your sound card.
14
15 DISCLAMER: You should check your sound card can handle the voltage.
16
17 .. _`this YHDC sensor`: https://learn.openenergymonitor.org/electricity-monitoring/ct-sensors/yhdc-sct-013-000-ct-sensor-report
18
19
20 Dependencies
21 ============
22
23 * apache2
24 * libapache2-mod-php | php-cgi | php-fpm
25 * python3-pyaudio
26 * python3-rrdtool
27 * rrdcached
28 * ...
29
30
31 Setup
32 =====
33
34 User setup
35 ----------
36
37 Ampy requires permission to use the sound card. It's recommanded to create a dedicated user::
38
39    addgroup --system ampy  # create a dedicated group
40    adduser --system --ingroup ampy --home /var/lib/ampy --disabled-password --disabled-login ampy
41    adduser ampy audio  # ampy can use audio
42    adduser www-data ampy  # httpd in group ampy
43
44
45 RRD database creation
46 ---------------------
47
48 Ampy uses the Round Robin Database provided by RRDtool.
49
50 ::
51
52     rrdtool create /var/lib/rrdcached/db/power.rrd \
53         --step 1s \
54         DS:watts:GAUGE:1s:0:10000 \
55         RRA:AVERAGE:0.5:1s:1d \
56         RRA:AVERAGE:0.5:1m:3d \
57         RRA:AVERAGE:0.5:15m:1w \
58         RRA:AVERAGE:0.5:1h:30d \
59         RRA:AVERAGE:0.5:1d:3y \
60         RRA:MAX:0.5:1d:3y \
61         RRA:AVERAGE:0.5:1month:10y \
62         RRA:MAX:0.5:1month:10y
63    chown ampy: /var/lib/rrdcached/db/power.rrd
64    chmod 664 /var/lib/rrdcached/db/power.rrd
65
66 Volume
67 ------
68
69 Capture volume should be as high as possible, without clipping. A good value is 0 dB::
70
71     root:~# amixer -c 1 contents
72     numid=23,iface=mixer,name='capture volume'
73       ; type=integer,access=rw---r--,values=2,min=0,max=46,step=0
74       : values=17,17
75       | dbscale-min=-16.00db,step=1.00db,mute=0
76
77 In that case volume should be set to 17.
78
79 You can also use ``alsamixer``. The control should show ``Capture [dB gain: 0.00, 0.00]``.
80
81
82 rrdcached setup
83 ---------------
84
85 rrdcached socket must be available to both ampy daemon and apache.
86
87 See/copy ``etc/rrdcached`` in ``/etc/default/rrdcached``.
88
89
90 Select the audio input
91 ----------------------
92
93 Run device.py to find out which entry you should use.
94
95 Then adjust DEVICE in run.py
96
97 At this point, ``sudo -u ampy run.py --norecord`` should run and give you a value.
98
99 Calibration
100 -----------
101
102 You'll need to adjust VOLUME_CONSTANT in run.py so that you get the correct voltage value.
103
104 Autostart
105 ---------
106
107 ::
108    ln -s /home/nirgal/ampy/etc/init /etc/init.d/ampy
109    update-rc.d ampy defaults
110
111 Apache
112 ------
113
114 Just point your DocumentRoot to the ampy/html directory.
115
116 You should really password protect the access with something. Create a password file::
117
118     root:~# htpasswd /var/lib/ampy/htusers myusername
119
120 Then add something like that in your apache configuration file::
121
122    <Location />
123        AuthType Basic
124        AuthName "Ampy's Realm"
125        AuthUserFile /var/lib/ampy/htusers
126        Require valid-user
127    </Location>
128    # Certbot / let's encrypt challenge dir has no password:
129    <Location /.well-known>
130        Require all granted
131    </Location>
132
133
134 Counter initialization
135 ----------------------
136
137 If you have a relugar electric meter::
138
139    echo "123456" > /var/lib/ampy/counter
140    chown ampy: /var/lib/ampy/counter
141
142 Notes to cleanup (ignore that)
143 ==============================
144
145 ::
146
147     rrdtool create power.rrd --daemon /var/run/rrdcached.sock --step 1s DS:watts:GAUGE:1:0:6600 RRA:AVERAGE:0.5:1s:1d
148     # Buggy: nécessite des updates toutes les 500 ms
149
150
151     Ceci n'est pas rafraîchi très souvent:
152
153     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'
154     Alors que ça si:
155     watch -n 0.5 rrdtool lastupdate --daemon /var/run/rrdcached.sock /var/lib/rrdcached/db/power.rrd