Welcome to the third guide in reef-pi series.

See the second part of this series here

In this guide, we'll be building a temperature controller using reef-pi. Corals are sensitive to temperature fluctuations and only survive in specific temperature. Higher order animals, such as marine fish can withstand much higher temperature fluctuations than coral. Tropical corals thrive at 78 degrees Fahrenheit. In reef aquariums, submersible heaters are used to keep the tank temperature at 78 degrees. For places where the indoor temperature gets really hot, chillers are used to cool down the aquarium water temperature to the desired level. A temperature controller automates heater and chiller on/off by sensing aquarium temperature, in turn maintaining a stable aquarium temperature.

Heaters are also prone to failures. Heater failure is one of the most common causes of tank crash (loss of all tank inhabitants). Temperature controllers can shut down heaters and alert users when aquarium temperature goes outside a range, providing an extra layer of safety net.

This guide assumes you have a working reef-pi installation with power controller module enabled.

Temperature controller module in reef-pi does not require power controller features, i.e. users can use reef-pi to just monitor and log temperature, but for turning on/off heater or chiller requires power controller module. In this guide, we'll be extending the power controller.

We'll use submersible DS18B20 temperature sensors for monitoring temperature. The DS18b20 requires minimal circuit (only a single 4.7K resistor) for integration with Raspberry Pi. We'll use the existing PermaProto HAT for this. A DS18B20 sensor will be connected to the controller enclosure using a 3.5 mm audio jack. The probe itself will have a 3.5 mm male audio connector, and the controller enclosure will have a panel mount female audio jack connector.

Note: Due to our choice of 3.5 mm audio connector, we should always avoid plugging/unplugging the temperature sensor when reef-pi is running. Always power down reef-pi before connecting or disconnecting the sensor. The 3.5 mm audio jack causes +Ve and GND pins to be touched (shorted) every time the male connector is plugged in, causing the Raspberry Pi to reboot (which we do not want to happen).

reef-pi supports multiple DS18B20 sensors. It is common to use two or three of these for redundancy. I have tested with up to 7 sensors.

The DS18B20 sensor circuit requires only a 4.7K resistor to work with Raspberry Pi. We'll use the extra space available in Perma-Proto HAT to mount the 4.7 K resistor as well as three male header pins which will be used to connect with DS18B20 GND, +Ve and data wires. The sensor itself will be wired with a male audio jack and will be used to connect with the female audio jack mounted in the enclosure.

Following is a Fritzing breadboard view of the circuit. Two of the male header pin are directly connected to GND and 3.3V while the 4.7K resistor is used as a pull-up resistor (from the 3.3V power) on the data pin, in the center. 

Note: though we are using only a single DS18B20 sensor, it is possible to connect multiple sensors (I have tested with maximum 7 sensors). The wiring remains the same (since the underlying one-wire protocol is a bus).

Prepare Connectors

Connect a male audio jack with DS18B20 sensor. Assuming the tip of the male audio jack is upward, the longest terminal of the jack represents GND, left terminal represents +Ve and the right terminal represents data. Tin the DS18B20 wires and male audio connector terminals before soldering them together

This is how the temperature sensor will look once connected with a male audio jack

Solder the male end of three male-female jumper wires with the female audio jack. Strip the male end of jumper wires and tin both jumper wires as well as male audio jack terminals before soldering. Opposite to the male audio connector, when the female audio connector is arranged upwards, the longest terminal represents GND, left terminal represents +Ve, and right terminal represents data. Throughout this build, the data pin is represented by yellow wires which in turn connect to Raspberry Pi GPIO 4.

Making DS18B20 circuit

We'll be using 22 AWG solid core wires as jumpers to connect all the pins. The yellow wire is used to connect GPIO 4 with central male header pin. A 4.7K pull up resistor is soldered perpendicular to save space.

Since we are extending the power controller circuit, the entire DS18B20 circuit sits on the left side of the Perma Proto HAT, with ULN2803A (used by power controller circuit) sitting in central location, occupying bulk of the HAT.

Next, we'll mount the female audio jack in the enclosure.

The temperature controller only adds a single audio jack connector to the existing enclosure. Mounting the female audio connector is fairly easy. Drill a hole in the enclosure using a Dremel or drill driver. I prefer to keep all the connectors on the bottom side. In this case, the female audio jack is closer to the input power connector (a 2.1 mm barrel jack)

Re-mount the PermaProto HAT (and Raspberry Pi attached with it) in the enclosure.

The female panel mount audio jack is threaded and comes with a nut to attach it on an enclosure, which makes it trivial to mount them on these plastic enclosures. Connect the audio jack's jumper wires with appropriate male header pins. 

That's it, once wired, our temperature sensor module is ready for field testing. Close the enclosure lid. This is how the end product will look:

Next we'll move on to reef-pi software configuration of the temperature sensor.

Connect the temperature sensor with the enclosure and power up reef-pi.

Once up and running, make sure temperature capability is enabled. If not, enable it under the settings section of the configuration tab. Reload reef-pi every time settings are updated.

Refresh your browser after reef-pi is reloaded and the temperature tab should appear. Navigate to the temperature tab and create a new temperature controller by clicking on the "+" button. A new temperature item should be available from the Sensor drop-down (DS18B20 sensors always have a name starting with 28-). The enable option represents whether reef-pi will check this sensor or not. Once enabled, the Check Frequency option represents how frequently (seconds) reef-pi should check for sensor value. Next, the alert and control option allows sending an alert if the temperature goes outside a specified range or turning on heater or cooling devices. For this example, we'll just enable sensor monitoring.

Once created, the new temperature controller will appear in the list. We can now use this new temperature control to chart the sensor data.

Charts & Dashboard

reef-pi provides two types of charts for each temperature controller. The first type of chart is simply known as temperature which indicates the latest temperature at check interval granularity. reef-pi will store one days worth of data when check interval is set to 1 minute (1440 values).

The other temperature chart is known as tc or temperature controller. Temperature controller chart stores hourly average temperature along with heater and cooler usage (in seconds) for past thirty days.

Configure the main dashboard to enable both types of temperature chart for the new sensor.

Click on update to save the new dashboard configuration and then click on Back to dashboard. You should see the temperature charts in the main dashboard now. The example images are taken from a controller running for a few days. For new builds, the charts will be have limited data.

Adafruit IO

Other than the in-controller dashboard, reef-pi also allows data logging to the Adafruit IO data service. You can enable adafruit.io in the telemetry section under the configuration tab. You'll need to specify your adafruit.io username and AIO Key. Once enabled, reef-pi will start emitting data to adafruit.io. reef-pi will automatically create a feed named the same as temperature controller name and with a tc- prefix. This feed will hold the temperature data and can be used to create a dashboard in Adafruit.io. The following is an example temperature dashboard using Adafruit.io integration.

Temperature is one of the key requirement for reef aquariums. With this feature, reef keepers will be able to understand and explore daily and seasonal aquarium temperature variation while having an extra safety net during heater failure.

In the next guide, we'll build the necessary automation for stabilizing the second most important parameter of reef aquariums, salinity.