Mycodo 3.5 Manual

Preface

There may be many unforseen issues if multiple commands are sent in rapid succession, when using the web interface. Therefore, after pressing abutton, wait either for a response or for the page to time out before pressing another button.

Supported Devices/Sensors

Temperature Sensors

Raspberry Pi (integrated)

The Raspberry Pi has an integrated temperature sensor on the BCM2835 SoC that measure the temperature of the CPU/GPU. This is the easiest sensor to set up in Mycodo, as it is immediately available to be used.

DS18B20

The DS18B20 is a 1-Wire digital temperature sensor from Maxim IC. Each sensor has a unique 64-Bit Serial number, allowing for a huge number of sensors to be used on one data bus (GPIO 4).

Specifications:
Usable temperature range: -55 to 125°C (-67°F to +257°F)
9 to 12 bit selectable resolution
Uses 1-Wire interface- requires only one digital pin for communication
Unique 64 bit ID burned into chip
Multiple sensors can share one pin
±0.5°C Accuracy from -10°C to +85°C
Temperature-limit alarm system
Query time is less than 750ms
Usable with 3.0V to 5.5V power/data

Temperature/Humidity Sensors

DHT11

Specifications:
3 to 5V power and I/O
2.5mA max current use during conversion (while requesting data)
20-80% humidity readings with 5% accuracy
0-50°C temperature readings ±2°C accuracy
No more than 1 Hz sampling rate (once every second)

DHT22, AM2302

Compared to the DHT11, this sensor is more precise, more accurate and works in a bigger range of temperature/humidity, but its larger and more expensive.

Specifications:
0-100% humidity readings with 2% (10-90% RH) and 5% (0-10% RH and 90-100% RH) accuracy
-40 to 80°C temperature readings ±0.5°C accuracy
3 to 5V power and I/O
2.5mA max current use during conversion (while requesting data)
No more than 0.5 Hz sampling rate (once every 2 seconds)

AM2315

Specifications:
0-100% humidity readings with 1% (10-90% RH) and 3% (0-10% RH and 90-100% RH) accuracy
-20 to 80°C temperature readings ±0.1°C typical accuracy
3.5 to 5.5V power and I/O
10 mA max current use during conversion (while requesting data)
No more than 0.5 Hz sampling rate (once every 2 seconds)

SHT1x

(SHT10, SHT11, SHT15)

Specifications:
0-100% humidity readings with 2%-5% (10-90% RH) and 2%-7.5% (0-10% RH and 90-100% RH) accuracy
-40 to 125°C temperature readings ±0.5°C, ±0.4°C, and ±0.3°C typical accuracy (respectively)
2.4 to 5.5V power and I/O
No more than 0.125 Hz sampling rate (once every 8 seconds)

SHT7x

(SHT71, SHT75)

Specifications:
0-100% humidity readings with 2%-3% (10-90% RH) and 2%-5% (0-10% RH and 90-100% RH) accuracy
-40 to 125°C temperature readings ±0.4°C and ±0.3°C typical accuracy (respectively)
2.4 to 5.5V power and I/O
No more than 0.125 Hz sampling rate (once every 8 seconds)

CO2 Sensors

K-30

Specifications:
0 – 10,000 ppm (0-5,000 ppm within specifications)
Repeatability: ± 20 ppm ± 1 % of measured value within specifications
Accuracy: ± 30 ppm ± 3 % of measured value within specifications
Non-dispersive infrared (NDIR) technology
Sensor life expectancy: > 15 years
Self-diagnostics: complete function check of the sensor module
Warm-up time: < 1 min. (@ full specs < 15 min)
0.5 Hz sampling rate (once every 2 seconds)

Pressure Sensors

BMP085, BMP180

The BMP180 is the next-generation of sensors from Bosch, and replaces the BMP085. It is completely identical to the BMP085 in terms of firmware/software/interfacing.

Specifications:
300-1100 hPa (9000m to -500m above sea level)
Up to 0.03hPa / 0.25m resolution
-40 to +85°C operational range
+-2°C temperature accuracy
Vin: 3 to 5V
Logic: 3 to 5V compliant
I2C 7-bit address 0x77

I2C Multiplexers

TCA9548A

The TCA9548A I2C allows multiple sensors that have the same I2C address to be used with mycodo (such as the AM2315). The multiplexer has a selectable address, from 0x70 through 0x77, allowing up to 8 multiplexers to be used at once. With 8 channels per multiplexer, this allows up to 64 devices with the same address to be used.

Web Interface

Go to http://127.0.0.1/mycodo/index.php (replace 127.0.0.1 with the correct domain name or IP address of your system) and log in with the credentials you created when you ran update-database.py. You will be greeted by a header with various information about the currently-logged in user, the status of the daemon, system performance statistics, and an area for information about sensors (when they are activated).

Many input boxes and buttons in the web interface will display descriptions or instructions when the mouse is hovered over them. Use this information in addition to the manual to learn how to configure the system.

The icon to the left of the word "Daemon", at the top-left, indicates if the daemon is running (green) or if it is not (red). If the daemon is not running, sensor measurements, logging, and PID regulation will not operate.

Graph Tab

This is the main landing page after logging in to Mycodo. It will look empty until sensors begin logging measurements and a graph can be generated of the historical data. See the Sensor Tab for setting up sensors.

Generating Graphs

There are two types of graphs that can be generated, a static graph or a dynamic graph. Static graphs are generated server-side and will be transmitted as an image to your browser. A dynamic graph will only have the sensor data transmitted to your browser and javascript will render a graph client-side.

The static graph has two options that define the type of graph and duration. The type of graph can be either Seperate or Combined. A Seperate graph will plot a new graph for each sensor. A Combined graph will plot a new graph for each measured condition. For example, A Seperate graph will plot both temperature and humidity from the data from a sensor that measures both temperature and humidity. A Combined graph will plot all temperateures on one graph and all humidities on another graph. The duration on x-axis can be chosen from a range of 1 hour to 6 months. If you desire a custom range, see the Custom Tab.

The dynamic graph has twe options that define the duration of time to collect of sensor data and of what sensor to accumulate the data from. A graph will be rendered with all relays and the selected sensor's data. "All Sensors" will render the data from all configured sensors. The dynamic graph permits showing/hiding data on the chart by selecting it in the legend. When zoomed out, data will aggregate in order to display a more readable graph. Data may be zoomed in to allow more data points to be revealed, decreasing aggregation and increasing resolution. When used with a touch-device, timeline dragging and pinch-zooming are additional options.

Note: To increase performance and reduce needless processing power, the generation of a static graph will only occur under certain circumstances. Clicking "Refresh Page" or refreshing the page (without resubmitting form data) will not generate a static graph. Clicking "Generate Graph" will always generate a static graph. Enabling Auto Refresh on the Graph Tab will always generate a static graph. Clearing cookies will cause a static graph to generate the next time any page is loaded.

Automatic Refresh

When activted, the Automatic Refresh option will force the page to refresh for the duration of time defined in the Settings Tab. If Auto Refresh was activated on the Graph Tab, the refreshed page will stay on the Graph Tab as well as generate a new static graph from current measurement data, whcih is useful to have a constantly-updated static graph displayed. Auto refresh can also be enabled on the Sensor Tab (useful for viewing the current status of relays) and the Camera Tab (useful for keeping the current image during a time-lapse).

Sensor Tab

Here is where the configuration of relays, sensors, timers, PID controllers, and conditional statements will occur.

Relays

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.

Relays must be properly set up before PID regulation can be achieved. Add and configure relays in the Sensor tab. Set the "GPIO Pin" to the BCM GPIO number of each pin that activates each relay. "Signal ON" should be set to the signal that activates the relay (closes the relay circuit). If your relay activates when the potential across the coil is 0-volts, set "Signal ON" to "Low", otherwise if your relay activates when the potential across the coil is 5-volts, set it to "High".

Sensors

Sensors will acquire environmental measurements, which will be used to create historical logs and provide the mos recent measurement for any PID controllers to operate from, allowing modulation of relays to regulate the environment.

Main Sensor Setup
Option Description
Name This is a unique name you can give this sensor, which will allow you to easily recognize it with a familiar name.
Device If there is support for more than one of a particular type of sensor, select which sensor is being used.
Serial Number or GPIO or Multiplexer address/channel Depending on what sensor is being used, you will need to either enter the serial number (in the case of the DS18B20 temperature sensor), the GPIO pin (in the case of sensors read by a GPIO), or the I2C address and channel if using the TCA9548A I2C multiplexer.
Log Interval After the sensor is successfully read and a log entry is made, this is the duration of time that is waited until the sensor is measured again for a log entry.
Pre Relay 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.
Pre Duration This is the duration of time that the Pre Relay runs for before the sensor measurement is obtained.
Log Enable saving sensor measurements to the log at the duration set by "Log Interval".
Graph Enable the generation of static graphs for this sensor.
Presets These are saved sensor configurations. There is a permanent preset named 'daefault', which is the current configuration that is displayed. If a saved preset is restored, it will overwrite the 'default' preset with the saved configuration.
Load Select a preset and this button will overwrite the current configuration with the preset's configuration.
Save Use this button to overwrite a preset with the current sensor configuration. You may save to the 'default' preset (the current configuration) or select a different preset to overwrite that preset's saved configuration.
Delete Select a preset and use this button to delete the preset.
New Enter a name and use this button to create a new preset.
Rename Select a preset and enter a name, then use this button to rename the preset to the new name.
Sensor Verification
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 specificed.
GPIO This is the GPIO pin of the sensor that will be used to verify the sensor measurement. The sensor of this GPIO will be read directly after the first sensor's measurement to verify whether the sensors have similar measurements.
Temperature Difference This is the maximum measured temperature difference between the two sensors before an action is triggered (either notify by email or prevent PID from operating; more below).
Notify If the temperatures of the two sensors differ by more than the set Temperature Difference, an email will be sent to the address in the Notification field.
Stop PID If the temperatures of the two sensors differ by more than the set Temperature Difference, and the Temperature PID controller is turned on, the PID will be prevented from updating and the PID relay will be prevented from turning on.
Humidity Difference This is the maximum measured humidity difference between the two sensors before an action is triggered (either notify by email or prevent PID from operating; more below).
Notify If the humidities of the two sensors differ by more than the set Temperature Difference, an email will be sent to the address in the Notification field.
Stop PID If the humidities of the two sensors differ by more than the set Temperature Difference, and the Temperature PID controller is turned on, the PID will be prevented from updating and the PID relay will be prevented from turning on.
Notification This is the email address that will be notified if the measurement differences surpass the set limit.
Graph Y-Axis Range & Marks
Min The lower end of the y-axis range that will be plotted on the static graph.
Max The higher end of the y-axis range that will be plotted on the static graph.
Tics This determines the number of graduations between the minimum and maximum values. Horizontal lines are also created across the entire static graph at these marks. Each graduation will occur for the number of units that this is set to. For example, if the min is 0, the max is 100, and Tics is 20, there will be marks at 20, 40, 60, and 80.
mTics This determines the number of marks between Tics. These do not include horizontal lines that span the whole static graph. In the above example, if mTics is set to 5, there will be extra marks at 25, 30, and 35. If mTics is set to 10, there will be extra marks at 30.
Graph Up These are the relay numbers that the on durations will be displayed as a positive value and will graph above 0 on the Relay Graph y-axis. Separate multiple relays with commas.
Graph Down These are the relay numbers that the on durations will be displayed as a negative value and will graph below 0 on the Relay Graph y-axis. Separate multiple relays with commas.
PID Regulation
Activate Turn a particular PID controller on or off.
Set Point This is the specific point you would like the environment to be regaulted at.
Regulate This is the direction that you wish to regulate. For instance, 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."
Measure Interval 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.
Up Relay 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.
Up Min 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.
Up Max 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.
Down Relay This is the relay that will cause the particular environmental condition to lower. In the case of lowering the CO2, this may be an exhaust fan.
Down Min 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.
Down Max 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.
Kp Porportional coefficient (non-negative). Accounts for present values of the error.
Ki Integral coefficient (non-negative). Accounts for past values of the error.
Kd Derivative coefficient (non-negative). Accounts for predicted future values of the error, based on its current rate of change.
For more details about PID controllers, see Discrete PID Control

Timers

Timers enable a relay to be switched on and off at specific durations. For Duration Timers, 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 Daily Timers, the start hour:minute and on duration can be set to turn a specific realy on at a specific time of day.

Conditional Statements

A conditional statement is a way to perform certain actions based on whether a condition is true. Conditional statements can be created for both relays and sensors. Possible conditional statements include:

If relay #1 turns on, turn relay #3 on
If relay #1 turns off, turn relay #3 off
If relay #1 turns on, turn relay #4 on for 40 seconds and notify critical-issue@domain.com
If relay #2 turns on, turn relay #4 on for 21 seconds
If relay #4 turns on for 21 seconds, turn relay #5 on for 50 seconds
If relay #4 turns on for 20 seconds, turn relay #1 off
If Humidity is Greater Than 80%, turn relay #4 on for 40 seconds
If Humidity if Less Than 50%, turn relay #1 on for 21 seconds, execute '/usr/local/bin/myscript.sh', and notify minor-issue@domain.com

Before activating any conditional statements or PID controllers, it"s advised to thoroughly explore all possible scenarios and plan a configuration that eliminates conflicts. Then, trial run your configuration before connecting devices to the relays. Some devices or relays may respond atypically or fail when switched on and off in rapid succession. Therefore, avoid creating an infinite loop with conditional statements.

Discrete PID Control

The PID controller is the most common regulatory controller found in industrial settings, for it"s ability to handle both simple and complex regulation. The PID controller has three paths, the proportional, integral, and derivative.

The Proportional takes the error and multiplies it by the constant Kp, to yield an output value. When the error is large, there will be a large proportional output.

The Integral takes the error and multiplies it by Ki, then integrates it (Ki · 1/s). As the error changes over time, the integral will continually sum it and multiply it by the constant Ki. The integral is used to remove perpetual error in the control system. If using Kp alone produces an output that produces a perpetual error (i.e. if the sensor measurement never reaches the Set Point), the integral will increase the output until the error decreases and the Set Point is reached.

The Derivative multiplies the error by Kd, then differentiates it (Kd · s). When the error rate changes over time, the output signal will change. The faster the change in error, the larger the derivative path becomes, decreasing the output rate of change. This has the effect of dampening overshoot and undershoot (oscillation) of the Set Point.

Using temperature as an example, the Process Variable (PV) is the sensed temperature, the Set Point (SP) is the desired temperature, and the Error (e) is the distance between the measured temperature and the desired temperature (indicating if the actual temperature is too hot or too cold and to what degree). The error is manipulated by each of the three PID components, producing an output, called the Manipulated Variable (MV) or Control Variable (CV). To allow control of how much each path contributes to the output value, each path is multiplied by a gain (represented by K). By adjusting the gains, the sensitivity of the system to each path is affected. When all three paths are summed, the PID output is produced. If a gain is set to 0, that path does not contribute to the output and that path is eessentially turned off.

The output can be used a number of ways, however this controller was designed to use the ouput to affect the sensed value (PV). This feedback loop, with a properly tuned PID controller, can achieve a set point in a short period of time, maintain regulation with little oscillation, and respond quickly to disturbance.

Therefor, if one would be regulating temperature, the sensor would be a temperature sensor and the feedback device(s) would be able to heat and cool. If the temperature is lower than the Set Point, the output value would be positive and a heater would activate. The temperature would rise toward the desired temperature, causing the error to decrease and a lower output to be produced. This feedback loop would continue until the error reaches 0 (at which point the output would be 0). If the temperature continues to rise past the Set Point (this is may be aceptable, depending on the degree), the PID would produce a negative output, which could be used by the cooling device to bring the temperature back down, to reduce the error. If the temperature would normally lower without the aid of a cooling device, then the system can be simplified by omitting a cooler and allowing it to lower on its own.

Implementing a controller that effectively utilizes P, I, and D can be challenging. Furthermore, it is often unnecessary. For instance, the I and D can be set to 0, effectively turning them off and producing the very popular and simple P controller. Also popular is the PI controller. It is recommended to start with only P activated, then experiment with PI, before finally using PID. Because systems will vary (e.g. airspace volume, degree of insulation, and the degree of impact from the connected device, etc.), each path will need to be adjusted through experimentation to produce an effective output.

Quick Set-up Examples

These example setups are meant to illustrate how to configure regulation in particular directions, and not to achieve ideal values to configure your P, I, and D variables. There are a number of online resources that discuss techniques and methods that have been developed to determine ideal PID values (such as here, here, here, here, and here) and since there are no universal values that will work for every system, it is recommended to conduct your own research to understand the variables and essential to conduct your own experiments to effectively implement them.

Provided merely as an example of the variance of PID values, one of my setups had temperature PID values (up regulation) of P=30, I=1.0, and D=0.5, and humidity PID values (up regulation) of P=1.0, I=0.2, and D=0.5. Furthermore, these values may not have been optimal but they worked well for the conditions of my environmental chamber.

Exact Temperature Regulation

This will set up the system to raise and lower the temperature to a certain level with two regulatory devices (one that heats and one that cools).

Select the number of sensors that are connected. Select the proper device and GPIO pin for each sensor and activate logging and graphing.

Stop here. Wait 10 minutes, then go the Main tab and generate a graph. If the graph generates with data on it, continue. If not, stop and investigate why there is no sensor data. The PID controller will not function if there is not sensor data being acquired.

Under the Temperature PID for an active sensor, change "PID Set Point" to the desired temperature, "PID Regulate" to Both. Set the "Up Relay" to the relay number attached to the heating device and the "Down Relay" to the relay number attached to the coolong device.

Set "P" to 1, "I" to 0, "D" to 0, then turn the Temperature PID on with the ON button.

If the temperature is lower than the Set Point, the heater should activate at some interval determined by the PID controller until the temperature rises to the set point. If the temperature goes higher than the Set Point (or Set Point + Buffer), the cooling device will activate until the temperature returns to the set point. If the temperature is not reaching the Set Point after a reasonable amount of time, increase the P value and see how that affects the system. Experiment with different configurations involving only "Read Interval" and "P" to achieve a good regulation. Avoid changing the "I" and "D" from 0 until a working regulation is achieved with P alone.

Generate 6-hour graphs from the Graph Tab to identify how well the temperature is regulated to the Set Point. What is meant by well-regulated will vary, depending on your specific application and tolerances. Most applications of a PID controller would like to see the proper temperature attained within a reasonable amount of time and with little oscillation.

Once regulation is achieved, experiment by reducing P slightly (~25%) and increasing "I" by a low amount to start, such as 0.1 (or lower), then observe how the controller regulates. Slowly increase I until regulation becomes both quick yet there is little oscillation once regulation is achieved. At this point, you should be fairly familiar with experimenting with the system and the D value can be experimented with.

High Temperature Regulation

Often the system can be simplified if two-way regulation is not needed. For instance, if cooling is unnecessary, this can be removed from the system and only up-regulation can be used.

Use the same configuration as the Exact Temperature Regulation example, except change "PID Regulate" to "Up" and do not touch the "Down Relay" section.

Custom Tab

Graph data can be plotted from any start and end times, so long as the beginning time is before the end time. As with the Graph Tab, graphs can be generated seperately or combined.

Camera Tab

There is currently only support for the Raspberry Pi camera. The camera can be instructed to capture images, stream video, or operate on a timer to produce a time-lapse series.

Data Tab

Here is where all the system data can be viewed and edited (in the case of notes), and where system backups and restores can be initiated from. Additionally, a number of lines may be defined (default of 30 if left blank) to restrict the output to a certain number of lines (for instance, if you only want to view the last 100 lines of a 100,000-line log). Notes and Git Commits (commits ahead only) will always show in their entirety.

System Backup

You may create a full backup of Mycodo at any time. This may be desirable if you are experimenting with creating custom code. A backup can be created from the "Create New System Bacup" button after pressing the "Backup/Restore" button under the Data Tab.

System Restore

You may restore a backup of Mycodo and bring it back to a previous version. This may be desirable if an update happens to break your system. To view all backups (or create a backup), select the "Backup/Restore" button under the Data Tab. If you would like to view the backups in the context of github updates, use the "Git Commits" button under the data tab. When viewing git commits, existing backups will be displayed under the commit for which the system was at during the time of the backup.

To ensure no data is lost, when a backup is restored, a backup of the current system is also created.

Settings Tab

Update You may update Mycodo to the latest version with the "Update Mycodo" button. A backup of the old system will be made to /var/Mycodo-backups/. Note: All logs and databases will be preserved during the update process. If you wish to return to a previous backup, see System Restore.
Daemon These options allow the stopping and starting of the Mycodo daemon that performs all the background tasks such as reading sensors, generating graphs, and operating PID controllers. The daemon can also be started in debug mode from here, providing a more verbose Daemon Log that may facilitate diagnosing issues.
System

The maximum amperage draw is the largest number of amps that are permitted to be activated by the Mycodo system when activating relays. If the maximum amperage limit will be surpassed if a particular relay is turned on, the system will prevent that relay form turning on.

The automatic refresh duration is the amount of time to wait between page refreshes when "Auto Refresh" is enabled (Graph Tab, Sensor Tab, and Camera Tab.

Display A custom message can be placed on the login page. This field accepts HTML and can be used for a number of purposes, such as a simple wencome message or to instruct visiting users how to log in with the guest account.
Email Notification The email notification settings will configure the system to log in and email the specified user (from the Sensor Tab) when a notification needs to be made. Currently only SMTP is supported.
Camera Settings These settings allow a relay to be activated while the camera is being used, change paths and format the image file name, send command parameters to raspistill, and execute commands in a linux shell before and after camera use.
User Settings In this section, users can be created or deleted and email addresses and passwords can be changed.

Preserving Custom Code

As per the work done by Boomstick8x, the process to preserve custom code edits and restore them after a Mycodo update is below. Be aware that this method does not guarantee the successful operation of Mycodo after restoring custom code, as it can't be unknown what is changed in an update. It's assumed that if you're producing custom code, you should also be familiar with analyzing the changes of an update to determine if your code edits will work.
Stash uncommited changes and apply them after an update:
1. git stash Save uncommited changes to git stack (use git stash list to see the stack)
2. Update Mycodo
3. git stash apply Apply the last saved changes to updated version (git stash pop can be used to apply changes from the stack and then drop the stack)
4. Check if everything worked
5. git stash drop Drop last saved stash (if git stash pop wasn't used)
Creating a patch file of changes and restoring them after an update:
1. git stash Stash changes
2. git stash show -p > name.patch Stash output in a patch file (add --binary option after -p if we also need to stash binary files: git stash show -p --binary > name.patch)
3. git apply --stat name.patch View is everything looks good
4. git apply --check name.patch Verify no errors
5. git apply name.patch Apply the patch

Tips

Because submitting certain configuration changes (mainly from the Sensor Tab) will require the daemon to reload the SQLite database before refreshing the web interface, the page-load time will potentially be faster when the daemon is not running. The daemon can be stopped and started in the Settings Tab.