forked from kizniche/Mycodo
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmycodo-manual.html
1457 lines (1397 loc) · 758 KB
/
mycodo-manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title></title>
<style type="text/css">code{white-space: pre;}</style>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<style>
html {
font-size: 100%;
overflow-y: scroll;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
body {
color: #444;
font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
font-size: 12px;
line-height: 1.7;
padding: 1em;
margin: auto;
max-width: 90%;
background: #fefefe;
}
a {
color: #0645ad;
text-decoration: none;
}
a:visited {
color: #0b0080;
}
a:hover {
color: #06e;
}
a:active {
color: #faa700;
}
a:focus {
outline: thin dotted;
}
*::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
*::selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
a::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
a::selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
p {
margin: 1em 0;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
color: #111;
line-height: 125%;
margin-top: 2em;
font-weight: normal;
}
h4, h5, h6 {
font-weight: bold;
}
h1 {
font-size: 2.5em;
}
h2 {
font-size: 2em;
}
h3 {
font-size: 1.5em;
}
h4 {
font-size: 1.2em;
}
h5 {
font-size: 1em;
}
h6 {
font-size: 0.9em;
}
blockquote {
color: #666666;
margin: 0;
padding-left: 3em;
border-left: 0.5em #EEE solid;
}
hr {
display: block;
height: 2px;
border: 0;
border-top: 1px solid #aaa;
border-bottom: 1px solid #eee;
margin: 1em 0;
padding: 0;
}
pre, code, kbd, samp {
color: #000;
font-family: monospace, monospace;
_font-family: 'courier new', monospace;
font-size: 0.98em;
}
pre {
white-space: pre;
white-space: pre-wrap;
word-wrap: break-word;
}
b, strong {
font-weight: bold;
}
dfn {
font-style: italic;
}
ins {
background: #ff9;
color: #000;
text-decoration: none;
}
mark {
background: #ff0;
color: #000;
font-style: italic;
font-weight: bold;
}
sub, sup {
font-size: 75%;
line-height: 0;
position: relative;
vertical-align: baseline;
}
sup {
top: -0.5em;
}
sub {
bottom: -0.25em;
}
ul, ol {
margin: 1em 0;
padding: 0 0 0 2em;
}
li p:last-child {
margin-bottom: 0;
}
ul ul, ol ol {
margin: .3em 0;
}
dl {
margin-bottom: 1em;
}
dt {
font-weight: bold;
margin-bottom: .8em;
}
dd {
margin: 0 0 .8em 2em;
}
dd:last-child {
margin-bottom: 0;
}
img {
border: 0;
-ms-interpolation-mode: bicubic;
vertical-align: middle;
}
figure {
display: block;
text-align: center;
margin: 1em 0;
}
figure img {
border: none;
margin: 0 auto;
}
figcaption {
font-size: 0.8em;
font-style: italic;
margin: 0 0 .8em;
}
table {
margin-bottom: 2em;
border-bottom: 1px solid #ddd;
border-right: 1px solid #ddd;
border-spacing: 0;
border-collapse: collapse;
}
table th {
padding: .2em 1em;
background-color: #eee;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
}
table td {
padding: .2em 1em;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
vertical-align: top;
}
.author {
font-size: 1.2em;
text-align: center;
}
@media only screen and (min-width: 480px) {
body {
font-size: 14px;
}
}
@media only screen and (min-width: 768px) {
body {
font-size: 16px;
}
}
@media print {
* {
background: transparent !important;
color: black !important;
filter: none !important;
-ms-filter: none !important;
}
body {
font-size: 12pt;
max-width: 100%;
}
a, a:visited {
text-decoration: underline;
}
hr {
height: 1px;
border: 0;
border-bottom: 1px solid black;
}
a[href]:after {
content: " (" attr(href) ")";
}
abbr[title]:after {
content: " (" attr(title) ")";
}
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after {
content: "";
}
pre, blockquote {
border: 1px solid #999;
padding-right: 1em;
page-break-inside: avoid;
}
tr, img {
page-break-inside: avoid;
}
img {
max-width: 100% !important;
}
@page :left {
margin: 15mm 20mm 15mm 10mm;
}
@page :right {
margin: 15mm 10mm 15mm 20mm;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3 {
page-break-after: avoid;
}
}
</style>
</head>
<body>
<h1 id="mycodo-manual">Mycodo Manual</h1>
<h1 id="table-of-contents">Table of Contents</h1>
<p><a href="#about-mycodo">About Mycodo</a></p>
<p><a href="#frequently-asked-questions">Frequently Asked Questions</a></p>
<p><a href="#upgrading">Upgrading</a></p>
<p><a href="#settings">Settings</a></p>
<ul>
<li><a href="#general-settings">General Settings</a></li>
<li><a href="#relay-usage-settings">Relay Usage Settings</a></li>
<li><a href="#users">Users</a></li>
<li><a href="#user-roles">User Roles</a></li>
<li><a href="#alert-settings">Alert Settings</a></li>
<li><a href="#camera-settings">Camera Settings</a></li>
</ul>
<p><a href="#controllers">Controllers</a></p>
<ul>
<li><a href="#sensors">Sensors</a></li>
<li><a href="#relays">Relays</a></li>
<li><a href="#pids">PIDs</a></li>
<li><a href="#timers">Timers</a></li>
<li><a href="#lcds">LCDs</a></li>
</ul>
<p><a href="#controller-functions">Controller Functions</a></p>
<ul>
<li><a href="#conditional-statements">Conditional Statements</a></li>
<li><a href="#methods">Methods</a></li>
</ul>
<p><a href="#pid-tuning">PID Tuning</a></p>
<ul>
<li><a href="#pid-control-theory">PID Control Theory</a></li>
<li><a href="#quick-setup-examples">Quick Setup Examples</a></li>
<li><a href="#exact-temperature-regulation">Exact-Temperature Regulation</a></li>
<li><a href="#high-temperature-regulation">High-Temperature Regulation</a></li>
</ul>
<p><a href="#miscellaneous">Miscellaneous</a></p>
<ul>
<li><a href="#graphs">Graphs</a></li>
<li><a href="#camera">Camera</a></li>
<li><a href="#relay-usage">Relay Usage</a></li>
<li><a href="#system-backup">System Backup</a></li>
<li><a href="#system-restore">System Restore</a></li>
</ul>
<p><a href="#troubleshooting">Troubleshooting</a></p>
<ul>
<li><a href="#daemon-not-running">Daemon Not Running</a></li>
<li><a href="#more">More</a></li>
</ul>
<p><a href="#sensor-and-device-setup">Sensor and Device Setup</a></p>
<p><a href="#sensor-interfaces">Sensor Interfaces</a></p>
<ul>
<li><a href="#1-wire">1-Wire</a></li>
<li><a href="#gpio">GPIO</a></li>
<li><a href="#uart">UART</a></li>
<li><a href="#i2c">I<sup>2</sup>C</a></li>
<li><a href="#edge-detection">Edge Detection</a></li>
</ul>
<p><a href="#device-setup">Device Setup</a></p>
<ul>
<li><a href="#i2c-multiplexers">I<sup>2</sup>C Multiplexers</a></li>
<li><a href="#analog-to-digital-converters">Analog to Digital Converters</a></li>
</ul>
<p><a href="#device-specific-information">Device Specific Information</a></p>
<p><a href="#temperature-sensors">Temperature Sensors</a></p>
<ul>
<li><a href="#raspberry-pi">Raspberry Pi</a></li>
<li><a href="#atlas-scientific-pt-1000">Atlas Scientific PT-1000</a></li>
<li><a href="#ds18b20">DS18B20</a></li>
<li><a href="#tmp006-tmp007">TMP006, TMP007</a></li>
</ul>
<p><a href="#temperature-humidity-sensors">Temperature, Humidity Sensors</a></p>
<ul>
<li><a href="#am2315">AM2315</a></li>
<li><a href="#dht11">DHT11</a></li>
<li><a href="#dht22-am2302">DHT22, AM2302</a></li>
<li><a href="#htu21d">HTU21D</a></li>
<li><a href="#sht1x">SHT1x</a></li>
<li><a href="#sht7x">SHT7x</a></li>
</ul>
<p><a href="#co2-sensors">CO2 Sensors</a></p>
<ul>
<li><a href="#k-30">K-30</a></li>
</ul>
<p><a href="#moisture-sensors">Moisture Sensors</a></p>
<ul>
<li><a href="#chirp">Chirp</a></li>
</ul>
<p><a href="#pressure-sensors">Pressure Sensors</a></p>
<ul>
<li><a href="#bme280">BME280</a></li>
<li><a href="#bmp085-bmp180">BMP085, BMP180</a></li>
</ul>
<p><a href="#luminosity-sensors">Luminosity Sensors</a></p>
<ul>
<li><a href="#bh1750">BH1750</a></li>
<li><a href="#tsl2561">TSL2561</a></li>
</ul>
<p><a href="#analog-to-digital-converters">Analog to Digital Converters</a></p>
<ul>
<li><a href="#ads1x15">ADS1x15</a></li>
<li><a href="#mcp342x">MCP342x</a></li>
</ul>
<p><a href="#diagrams">Diagrams</a></p>
<ul>
<li><a href="#dht11-diagrams">DHT11 Diagrams</a></li>
<li><a href="#ds18b20-diagrams">DS18B20 Diagrams</a></li>
<li><a href="#raspberry-pi-and-relay-diagrams">Raspberry Pi and Relay Diagrams</a></li>
</ul>
<hr />
<h1 id="about-mycodo">About Mycodo</h1>
<p>Mycodo is a remote monitoring and automated regulation system with a focus on modulating environmental conditions. It was built to run on the Raspberry Pi (versions Zero, 1, 2, and 3) and aims to be easy to install and set up.</p>
<p>The core system coordinates a diverse set of responses to sensor measurements, including actions such as camera captures, email notifications, relay activation/deactivation, regulation with PID control, and more. Mycodo has been used for cultivating gourmet mushrooms, cultivating plants, culturing microorganisms, maintaining honey bee apiary homeostasis, incubating snake eggs and young animals, aging cheeses, fermenting foods, maintaining aquatic systems, and more.</p>
<p>A <a href="https://en.wikipedia.org/wiki/PID_controller">proportional-derivative-integral (PID) controller</a> is a control loop feedback mechanism used throughout industry for controlling systems. It efficiently brings a measurable condition, such as the temperature, to a desired state and maintains it there with little overshoot and oscillation. A well-tuned PID controller will raise to the setpoint quickly, have minimal overshoot, and maintain the setpoint with little oscillation.</p>
<h1 id="frequently-asked-questions">Frequently Asked Questions</h1>
<p><em>Where do I even begin?</em></p>
<p>Here is how I generally set up Mycodo to monitor and regulate:</p>
<ol type="1">
<li>Determine what environmental condition you want to measure or regulate. Consider the devices that must be coupled to achieve this. For instance, temperature regulation require a temperature sensor and an electric heater and/or electric air conditioner.</li>
<li>Determine what relays you will need to power your electric devices. The Raspberry Pi is capable of directly switching relays (using a 3.3-volt signal), although opto-isolating the circuit is advisable. Be careful when selecting a relay not to exceed the current draw of the Raspberry Pi’s PGIO.</li>
<li>See the <a href="#device-specific-information">Device Specific Information</a> for information about what sensors are supported. Acquire one or more of these sensors and relays and connect them to the Raspberry Pi according to the manufacturer’s instructions.</li>
<li>On the <code>Sensors</code> page, create a new sensor, using the dropdown to select the correct sensor. Configure the sensor with the correct communication pins, etc. and save. Activate the sensor to begin recording measurements.</li>
<li>Go to the <code>Data</code> -> <code>Live Measurements</code> page to ensure there is recent data being acquired from the sensor.</li>
<li>On the <code>Relay</code> -> <code>Relays</code> page, add a relay and configure the GPIO pin that switches it, whether the relay switches On when the signal is HIGH or LOW, and what state (On or Off) to set the relay when Mycodo starts.</li>
<li>Test the relay by switching it On and Off from the <code>Relay</code> -> <code>Relays</code> page and make sure the device connected to the relay turns On when you select “On”, and Off when you select “Off”.</li>
<li>On the <code>PID</code> -> <code>PID Controllers</code> page, create a PID controller with the appropriate sensor, measurement, relay, and other parameters. Refer to the <a href="#quick-setup-examples">Quick Setup Examples</a> for setting up and tuning a PID controller.</li>
<li>On the <code>Data</code> -> <code>Live Graphs</code> page, create a graph that includes the sensor measurement, the relay that is being used by the PID, and the PID setpoint. This provides a good visualization for tuning and adjusting the system.</li>
</ol>
<hr />
<p><em>Why is there only one FAQ?</em></p>
<p>Good question.</p>
<hr />
<h1 id="upgrading">Upgrading</h1>
<p>If you already have Mycodo installed (version >= 4.0.0), you can perform an upgrade to the latest <a href="https://github.com/kizniche/Mycodo/releases">release</a> on github by either using the Upgrade option in the web UI (recommended) or by issuing the following command in a terminal. A log of the upgrade process is created at <code>/var/log/mycodo/mycodoupgrade.log</code></p>
<p><code>sudo /bin/bash ~/Mycodo/mycodo/scripts/upgrade_commands.sh upgrade</code></p>
<h1 id="settings">Settings</h1>
<p>The settings menu, accessed by selecting the gear icon in the top-right, then the Configure link, is a general area for various system-wide configuration options.</p>
<h2 id="general-settings">General Settings</h2>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Language</td>
<td style="text-align: left;">Set the language that will be displayed in the web user interface.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Force HTTPS</td>
<td style="text-align: left;">Require web browsers to use SSL/HTTPS. Any request to http:// will be redirected to https://.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Hide success alerts</td>
<td style="text-align: left;">Hide all success alert boxes that appear at the top of the page.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Hide info alerts</td>
<td style="text-align: left;">Hide all info alert boxes that appear at the top of the page.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Hide warning alerts</td>
<td style="text-align: left;">Hide all warning alert boxes that appear at the top of the page.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Opt-out of statistics</td>
<td style="text-align: left;">Turn off sending anonymous usage statistics. Please consider that this helps the development to leave on.</td>
</tr>
</tbody>
</table>
<h2 id="relay-usage-settings">Relay Usage Settings</h2>
<p>In order to calculate accurate relay usage statistics, a few characteristics of your electrical system needs to be know. These variables should describe the characteristics of the electrical system being used by the relays to operate electrical devices. Note: Proper relay usage calculations also rely on the correct current draw to be set for each relay (see <a href="#relays">Relay Settings</a>).</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Voltage</td>
<td style="text-align: left;">Alternating current (AC) voltage that is switched by the relays. This is usually 120 or 240.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Cost per kWh</td>
<td style="text-align: left;">This is how much you pay per kWh.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Currency Unit</td>
<td style="text-align: left;">This is the unit used for the currency that pays for electricity.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Day of Month</td>
<td style="text-align: left;">This is the day of the month (1-30) that the electricity meter is read (which will correspond to the electrical bill).</td>
</tr>
</tbody>
</table>
<h2 id="users">Users</h2>
<p>Mycodo requires at least one Admin user for the login system to be enabled. If there isn’t an Admin user, the web server will redirect to an Admin Creation Form. This is the first page you see when starting Mycodo for the first time. After an Admin user has been created, additional users may be created from the User Settings page.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Username</td>
<td style="text-align: left;">Choose a user name that is between 2 and 64 characters. The user name is case insensitive (all user names are converted to lower-case).</td>
</tr>
<tr class="even">
<td style="text-align: left;">Email</td>
<td style="text-align: left;">The email associated with the new account.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Password/Repeat</td>
<td style="text-align: left;">Choose a password that is between 6 and 64 characters and only contain letters, numbers, and symbols.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Role</td>
<td style="text-align: left;">Roles are a way of imposing access restrictions on users, to either allow or deny actions. See the table below for explanations of the four default Roles.</td>
</tr>
</tbody>
</table>
<h2 id="user-roles">User Roles</h2>
<p>Roles define the permissions of each user. There are 4 default roles that determine if a user can view or edit particular areas of Mycodo. Custom roles may be created, but these four roles may not be modified or deleted.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Role</th>
<th style="text-align: left;">Admin</th>
<th style="text-align: left;">Editor</th>
<th style="text-align: left;">Monitor</th>
<th style="text-align: left;">Guest</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Edit Users</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;">Edit Controllers</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr class="odd">
<td style="text-align: left;">Edit Settings</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;">View Settings</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
</tr>
<tr class="odd">
<td style="text-align: left;">View Camera</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
</tr>
<tr class="even">
<td style="text-align: left;">View Stats</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
</tr>
<tr class="odd">
<td style="text-align: left;">View Logs</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;">X</td>
<td style="text-align: left;"></td>
</tr>
</tbody>
</table>
<p><sup>1</sup>The <code>Edit Controllers</code> permission protects the editing of Graphs, LCDs, Methods, PIDs, Relays, Sensors, and Timers.</p>
<p><sup>2</sup>The <code>View Stats</code> permission protects the viewing of usage statistics and the System Info and Relay Usage pages.</p>
<h2 id="alert-settings">Alert Settings</h2>
<p>Alert settings set up the credentials for sending email notifications.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">SMTP Host</td>
<td style="text-align: left;">The SMTP server to use to send emails from.</td>
</tr>
<tr class="even">
<td style="text-align: left;">SMTP Port</td>
<td style="text-align: left;">Port to communicate with the SMTP server (465 for SSL, 587 for TSL).</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Enable SSL</td>
<td style="text-align: left;">Check to emable SSL, uncheck to enable TSL.</td>
</tr>
<tr class="even">
<td style="text-align: left;">SMTP User</td>
<td style="text-align: left;">The user name to send the email from. This can be just a name or the entire email address.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">SMTP Password</td>
<td style="text-align: left;">The password for the user.</td>
</tr>
<tr class="even">
<td style="text-align: left;">From Email</td>
<td style="text-align: left;">What the from email address be set as. This should be the actual email address for this user.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Max emails (per hour)</td>
<td style="text-align: left;">Set the maximum number of emails that can be sent per hour. If more notifications are triggered within the hour and this number has been reached, the notifications will be discarded.</td>
</tr>
</tbody>
</table>
<h2 id="camera-settings">Camera Settings</h2>
<p>Many cameras can be used simultaneously with Mycodo. Each camera needs to be set up in the camera settings, then may be used throughout the software. Note that not every option (such as Hue or White Balance) may be able to be used with your particular camera, due to manufacturer differences in hardware and software.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Type</td>
<td style="text-align: left;">Select whether the camera is a Raspberry Pi Camera or a USB camera.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Library</td>
<td style="text-align: left;">Select which library to use to communicate with the camera. The Raspberry Pi Camera uses picamera (and potentially opencv), and USB cameras should be set to opencv.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">OpenCV Device</td>
<td style="text-align: left;">Any devices detected by opencv will populate this dropdown list. If there are no values in this list, none were detected. If you have multiple opencv devices detected, try setting the camera to each device and take a photo to determine which camera is associated with which device.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Relay ID</td>
<td style="text-align: left;">This relay will turn on during the capture of any still image (which includes timelapses).</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Rotate Image</td>
<td style="text-align: left;">The number of degrees to rotate the image.</td>
</tr>
<tr class="even">
<td style="text-align: left;">…</td>
<td style="text-align: left;">Image Width, Image Height, Brightness, Contrast, Exposure, Gain, Hue, Saturation, White Balance. These options are self-explanatory. Not all options will work with all cameras.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Pre Command</td>
<td style="text-align: left;">A command to execute (as user mycodo) before a still image is captured.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Post Command</td>
<td style="text-align: left;">A command to execute (as user mycodo) after a still image is captured.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Flip horizontally</td>
<td style="text-align: left;">Flip, or mirror, the image horizontally.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Flip vertically</td>
<td style="text-align: left;">Flip, or mirror, the image vertically.</td>
</tr>
</tbody>
</table>
<h1 id="controllers">Controllers</h1>
<p>Controllers are essentially modules that can be used to perform functions or communicate with other parts of Mycodo. Each controller performs a specific task or group of related tasks. There are also Controller Functions, which are larger functions of a controller or controllers and have been given their own sections.</p>
<h2 id="sensors">Sensors</h2>
<p>Sensors measure environmental conditions, which will be stored in an influx database. This database will provide recent measurement for <a href="/help#conditional-statements">Conditional Statements</a> or <a href="/help#pids">PID Controllers</a> to operate from, among other uses.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Activate</td>
<td style="text-align: left;">After the sensor has been properly configured, activation begins acquiring measurements from the sensor. Any activated conditional statements will now being operating.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Deactivate</td>
<td style="text-align: left;">Deactivation stops measurements from being acquired from the sensor. All associated conditional statements will cease to operate.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Save</td>
<td style="text-align: left;">Save the current configuration entered into the input boxes for a particular sensor.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Delete</td>
<td style="text-align: left;">Delete a particular sensor.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Up/Down</td>
<td style="text-align: left;">Move a particular sensor up or down in the order displayed.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Location</td>
<td style="text-align: left;">Depending on what sensor is being used, you will need to either select a serial number (DS18B20 temperature sensor), a GPIO pin (in the case of sensors read by a GPIO), or an I<sup>2</sup>C address. and channel if using the TCA9548A I<sup>2</sup>C multiplexer.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">I<sup>2</sup>C Bus</td>
<td style="text-align: left;">The bus to be used to communicate with the I<sup>2</sup>C address. If you’re using an I<sup>2</sup>C multiplexer that provides multiple buses, this allows you to select which bus the sensor is connected to.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Period</td>
<td style="text-align: left;">After the sensor is successfully read and a database entry is made, this is the duration of time waited until the sensor is measured again.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Pre Relay</td>
<td style="text-align: left;">If you require a relay to be activated before a measurement is made (for instance, if you have a pump that extracts air to a chamber where the sensor resides), this is the relay number that will be activated. The relay will be activated for a duration defined by the Pre Duration, then once the relay turns off, a measurement by the sensor is made.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Pre Relay Duration</td>
<td style="text-align: left;">This is the duration of time that the Pre Relay runs for before the sensor measurement is obtained.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Edge</td>
<td style="text-align: left;">Edge sensors only: Select whether the Rising or Falling (or both) edges of a changing voltage are detected. A number of devices to do this when in-line with a circuit supplying a 3.3-volt input signal to a GPIO, such as simple mechanical switch, a button, a magnet (reed/hall) sensor, a PIR motion detector, and more.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Bounce Time (ms)</td>
<td style="text-align: left;">Edge sensors only: This is the number of milliseconds to bounce the input signal. This is commonly called <a href="http://kylegabriel.com/projects/2016/02/morse-code-translator.html#debouncing">debouncing a signal</a>. and may be necessary if using a mechanical circuit.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Reset Period</td>
<td style="text-align: left;">Edge sensors only: This is the period of time after an edge detection that another edge will not be recorded. This enables devices such as PIR motion sensors that may stay activated for longer periods of time.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Multiplexer (MX)</td>
<td style="text-align: left;">If connected to the TCA9548A I<sup>2</sup>C multiplexer, select what the I<sup>2</sup>C address of the multiplexer is.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Mx I<sup>2</sup>C Bus</td>
<td style="text-align: left;">If connected to the TCA9548A I<sup>2</sup>C multiplexer, select the I<sup>2</sup>C bus the multiplexer is connected to.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Mx Channel</td>
<td style="text-align: left;">If connected to the TCA9548A I<sup>2</sup>C multiplexer, select the channel of the multiplexer the device is connected to.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Measurement</td>
<td style="text-align: left;">Analog-to-digital converter only: The type of measurement being acquired by the ADC. For instance, if the resistance of a photocell is being measured through a voltage divider, this measurement would be “light”.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Units</td>
<td style="text-align: left;">Analog-to-digital converter only: This is the unit of the measurement. With the above example of “light” as the measurement, the unit may be “lux” or “intensity”.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Channel</td>
<td style="text-align: left;">Analog-to-digital converter only: This is the channel to obtain the voltage measurement from the ADC.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Gain</td>
<td style="text-align: left;">Analog-to-digital converter only: set the gain when acquiring the measurement.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Volts Min</td>
<td style="text-align: left;">Analog-to-digital converter only: What is the minimum voltage to use when scaling to produce the unit value for the database. For instance, if your ADC is not expected to measure below 0.2 volts for your particular circuit, set this to “0.2”.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Volts Max</td>
<td style="text-align: left;">Analog-to-digital converter only: This is similar to the Min option above, however it is setting the ceiling to the voltage range. Units Min Analog-to-digital converter only: This value will be the lower value of a range that will use the Min and Max Voltages, above, to produce a unit output. For instance, if your voltage range is 0.0 - 1.0 volts, and the unit range is 1 - 60, and a voltage of 0.5 is measured, in addition to 0.5 being stored in the database, 30 will be stored as well. This enables creating calibrated scales to use with your particular circuit.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Units Max</td>
<td style="text-align: left;">Analog-to-digital converter only: This is similar to the Min option above, however it is setting the ceiling to the unit range.</td>
</tr>
</tbody>
</table>
<h3 id="sensor-verification">Sensor Verification</h3>
<p>Sensor verification was introduced in an earlier version and was broken when the system moved to its new software framework. It was a great feature, and it’s planned to be integrated into the latest version.</p>
<p>This allows the verification of a sensor’s measurement with another sensor’s measurement. This feature is best utilized when you have two sensors in the same location (ideally as close as possible). One sensor (host) should be set up to use the other sensor (slave) to verify. The host sensor should be used to operate the PID, as one feature of the verification is the ability to disable the PID if the difference between measurements is not within the range specified.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">GPIO</td>
<td style="text-align: left;">This is the sensor that will be used to verify the sensor measurement. The sensor will be read directly after the first sensor’s measurement to verify whether the sensors have similar measurements.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Difference</td>
<td style="text-align: left;">This is the maximum measured measurement difference between the two sensors before an action is triggered (either notify by email or prevent PID from operating; more below).</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Notification</td>
<td style="text-align: left;">If the measurements of the two sensors differ by more than the set <em>Difference</em>, an email will be sent to the address in the <em>Notification</em> field.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Stop PID</td>
<td style="text-align: left;">If the measurements of the two sensors differ by more than the set <em>Difference</em>, the PID controller will turn off.</td>
</tr>
</tbody>
</table>
<h2 id="relays">Relays</h2>
<p>Relays are electromechanical or solid-state devices that enable a small voltage signal (such as from a microprocessor) to activate a much larger voltage, without exposing the low -voltage system to the dangers of the higher voltage.</p>
<p>Relays must be properly set up before PID regulation can be achieved. Add and configure relays in the Relay tab. Set the “GPIO Pin” to the BCM GPIO number of each pin that activates each relay. <em>On Trigger</em> should be set to the signal that activates the relay (the device attached to the relay turns on). If your relay activates when the potential across the coil is 0-volts, set <em>On Trigger</em> to “Low”, otherwise if your relay activates when the potential across the coil is 3.3-volts (or whatever switching voltage you are using, if not being driven by the GPIO pin), set it to “High”.</p>
<p>When a relay is initially added, the background of the new relay will be yellow, indicating it is not configured. When properly configured, it will either turn green, indicating the relay is activated (device is on), or red, indicating the relay is inactivated (device is off).</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">GPIO Pin</td>
<td style="text-align: left;">This is the GPIO that will be the signal to the relay.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Current Draw (amps)</td>
<td style="text-align: left;">The is the amount of current the device powered by the relay draws. Note: this value should be calculated based on the voltage set in the <a href="#relay-usage-settings">Relay Usage Settings</a>.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">On Trigger</td>
<td style="text-align: left;">This is the state of the GPIO to signal the relay to turn the device on. HIGH will send a 3.3-volt signal and LOW will send a 0-volt signal. If you relay completes the circuit (and the device powers on) when a 3.3-volt signal is sent, then set this to HIGH. If the device powers when a 0-volt signal is sent, set this to LOW.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Start State</td>
<td style="text-align: left;">This specifies whether the relay should be ON or OFF when mycodo initially starts.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Seconds to turn On</td>
<td style="text-align: left;">This is a way to turn a relay on for a specific duration of time. This can be useful for testing the relays and powered devices or the measured effects a device may have on an environmental condition.</td>
</tr>
</tbody>
</table>
<h2 id="pids">PIDs</h2>
<p>A <a href="https://en.wikipedia.org/wiki/PID_controller">proportional-derivative-integral (PID) controller</a> is a control loop feedback mechanism used throughout industry for controlling systems. It efficiently brings a measurable condition, such as the temperature, to a desired state and maintains it there with little overshoot and oscillation. A well-tuned PID controller will raise to the setpoint quickly, have minimal overshoot, and maintain the setpoint with little oscillation.</p>
<p>PID settings may be changed while the PID is activated and the new settings will take effect immediately. If settings are changed while the controller is paused, the values will be used once the controller resumes operation.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Activate/Deactivate</td>
<td style="text-align: left;">Turn a particular PID controller on or off.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Pause</td>
<td style="text-align: left;">When paused, the PID will not turn on the associated relays, and settings can be changed without losing current PID output values.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Hold</td>
<td style="text-align: left;">When held, the PID will turn on the associated relays, and settings can be changed without losing current PID output values.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Resume</td>
<td style="text-align: left;">Resume a PID controller from being held or paused.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Setpoint</td>
<td style="text-align: left;">This is the specific point you would like the environment to be regaulted at. For example, if you would like the humidity regulated to 60%, enter 60.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Direction</td>
<td style="text-align: left;">This is the direction that you wish to regulate. For example, if you only require the temperature to be raised, set this to “Up,” but if you require regulation up and down, set this to “Both.”</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Period</td>
<td style="text-align: left;">This is the duration between when the PID relay turns off amd when the sensor takes another measurement, the PID is updated, and the relay is turned on again for another duration.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Max Age</td>
<td style="text-align: left;">The time (in seconds) that the sensor measurement age is required to be less than. If the measurement is not younger than this age, the measurement is thrown out and the PID will not actuate the relay. This is a safety measure to ensure the PID is only using recent measurements.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Raise Relay</td>
<td style="text-align: left;">This is the relay that will cause the particular environmental condition to rise. In the case of raising the temperature, this may be a heating pad or coil.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Min Duration (raise)</td>
<td style="text-align: left;">This is the minimum that the PID output must be before the Up Relay turns on. If the PID output exceeds this minimum, the Up Relay will turn on for the PID output number of seconds.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Max Duration (raise)</td>
<td style="text-align: left;">This is the maximum duration the Up Relay is allowed to turn on for. If the PID output exceeds this number, the Up Relay will turn on for no greater than this duration of time.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Lower Relay</td>
<td style="text-align: left;">This is the relay that will cause the particular environmental condition to lower. In the case of lowering the CO<sub>2</sub>, this may be an exhaust fan.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Min Duration (lower)</td>
<td style="text-align: left;">This is the minimum that the PID output must be before the Down Relay turns on. If the PID output exceeds this minimum, the Down Relay will turn on for the PID output number of seconds.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Max Duration (lower)</td>
<td style="text-align: left;">This is the maximum duration the Down Relay is allowed to turn on for. if the PID output exceeds this number, the Down Relay will turn on for no greater than this duration of time.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">K<sub>P</sub></td>
<td style="text-align: left;">Proportional coefficient (non-negative). Accounts for present values of the error. For example, if the error is large and positive, the control output will also be large and positive.</td>
</tr>
<tr class="even">
<td style="text-align: left;">K<sub>I</sub></td>
<td style="text-align: left;">Integral coefficient (non-negative). Accounts for past values of the error. For example, if the current output is not sufficiently strong, the integral of the error will accumulate over time, and the controller will respond by applying a stronger action.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">K<sub>D</sub></td>
<td style="text-align: left;">Derivative coefficient (non-negative). Accounts for predicted future values of the error, based on its current rate of change.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Integrator Min</td>
<td style="text-align: left;">The minimum allowed integrator value, for calculating Ki_total: (Ki_total = Ki * integrator; and PID output = Kp_total + Ki_total + Kd_total)</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Integrator Max</td>
<td style="text-align: left;">The maximum allowed integrator value, for calculating Ki_total: (Ki_total = Ki * integrator; and PID output = Kp_total + Ki_total + Kd_total)</td>
</tr>
</tbody>
</table>
<h2 id="timers">Timers</h2>
<p>Timers enable a relay to be manipulated after specific durations of time or at a specific times of the day. For <em>Duration Timers</em>, both the on duration and the off duration can be defined and the timer will be turned on and off for those durations until deactivated. For <em>Daily Timers</em>, the start hour:minute can be set to turn a specific relay on or off at the specific time of day.</p>
<h2 id="lcds">LCDs</h2>
<p>Data may be output to a liquid crystal display (LCD) for easy viewing. There are only a few number fo LCDs that are supported. Only 16x2 and 20x4 character LCD displays with I<sup>2</sup>C backpacks are supported. Please see the README for specific information regarding compatibility.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Setting</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Reset Flashing</td>
<td style="text-align: left;">If the LCD is flashing to alert you because it was instructed to do so by a triggered Conditional Statement, use this button to stop the flashing.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Type</td>
<td style="text-align: left;">Select either a 16x2 or 20x4 character LCD display.</td>