Part 2 of 2: Implementation Details/How-To
(A) Wiring and GPIO Schematic
The DS18B20 temperature probe is used. For prototyping I used a solderless breadboard with jumper wires, but for a production model a 3-screw terminal and jumper wires was used to wire everything together. Refer to your specific product sheet for lead labels, but the generic wiring scheme for the sensor is:
There is a 4.7K-ohm pull-up resistor between the Vdd line (3.3V) and the GPIO line (Data). This can be done by soldering directly to the probe leads, using a screw terminal with jumper wires, or using a breadboard. The Vdd, GPIO and ground wires (GND) are then all connected to the appropriate GPIO pins on the Raspberry Pi (refer to the appropriate pinout for your specific raspberry pi model; for the raspberry pi 2, this is the pinout diagram I used). This is what my configuration looks like:
Once everything is connected up, we can move on to installing Raspbian and appropriate prerequisite software packages.
(B) Install Raspbian and Software Packages
Raspbian can be installed by directly writing a pre-configured image or installing it through a wizard that you simply extract on to your microSD or SD card (NOOBS). NOOBS would be the most straightforward way if you are just starting out, just follow the instructions as linked and Raspbian should be up and running without issue. Now configure your installation:
- you need to enable the 1-wire protocol in the boot configuration of your raspberry pi; edit the boot.txt file by running:
pi@raspberrypi ~ $ sudo nano /boot/config.txt
- in the raspi-config tool, change your locale to your appropriate timezone; this is useful to get accurate timestamps with your temperature data
- after installing raspbian, we are mostly going to be using and configuring it as a headless system (i.e. without using a mouse and keyboard on it directly); in order to do this, ssh must be enabled through the raspi-config utility (i.e. run raspi-config command via the terminal); that being said, it is also ok to initially configure your raspberry pi without ssh but it should be enabled for administrative tasks you might need to do later on
- you should update your raspberry pi after installation:
sudo apt-get update && sudo apt-get dist-upgrade
- Install the following packages (using sudo apt-get install):
sudo apt-get install ruby-dev apache2 sqlite3 php5 php5-sqlite heirloom-mailx msmtp-mta
- Reboot your system
B-2: Configure Email for Notifications
You have already installed the appropriate packages in step B-1 (heirloom-mailx, msmtp-mta) to allow us to send email through bash commands, so now we just have to configure a few files in our home directory to enable this. I am using a gmail account (I recommend making a separate account to act as a notification email address) so I’ll outline the configuration I used below.
NOTE: you must enable IMAP on your account and allow your google account to “use less secure apps” in order to use gmail with msmtp/mailx.
- create/edit .mailrc; in your home directory:
which should contain only the following lines:
set sendmail="/usr/bin/msmtp" set message-sendmail-extra-arguments="-a gmail"
- create/edit .msmtprc; in your home directory
which should contain only the following lines:
#Gmail Account Settings defaults logfile ~/msmtp.log account gmail auth on host smtp.gmail.com from <email address> auth on tls on tls_trust_file /usr/share/ca-certificates/mozilla/Equifax_Secure_CA.crt user <email address> password <password> port 587 account default : gmail
replace the bolded fields appropriately (do not include the brackets). Note that the 3rd line (parameter to denote the logfile) can be commented or deleted out if you do not wish to occupy more disk space or have your email contents recorded.
- test it out: run a mail command to an email to see if it works via the command line. The command should run without returning anything and you should see a corresponding email with subject line “test” and body “test message”
echo "test message" | mailx -s "test" <firstname.lastname@example.org>
You may receive an error message to the command line during testing which explains that the .msmtprc file must be read and write by the user only; use the chmod command with 600 to change this, if necessary (i.e. chmod 600 ~/.msmtprc). See the man page for chmod for more details.
B-3: Configure Twitter Notifications
Twitter offers an elegant way of messaging all of your devices in a platform-independent and quickly accessible way. It also doubles as a workaround to getting notified via their notification text message service. We have already installed the pre-requisite package “ruby-dev” in order to install the twitter tool:
- Install t. Install t via the gem installer:
sudo gem install t
- Set up a separate twitter account made only for your raspberry pi/notifications. Go to apps.twitter.com and create a new app; record the “consumer API” and “secret API” keys.
- Authorize your account. Run the authorization command to get your twitter account working with the t command line tool:
and follow the prompts. Read xmodulo’s guide for specific steps if you get stuck. If you are configuring your twitter authorization remotely via ssh, a browser window will not open and instead an error message will be shown with the URL on bash. When this error occurs, do not press enter; copy and paste the URL displayed on the command line, navigate to it using a web browser on your client and paste the appropriate field (API/API secret) before pressing Enter. Alternatively, you can use X window forwarding, VNC or configure raspberry pi in a fashion that is not headless.
- Your twitter account should now be linked with t! Test it out with some usage examples.
- Use another twitter account/your personal one to receive DM’s (or tweets) from the raspberry pi’s notification twitter account by simply following the account. A neat way to receive text message is to pair your mobile phone with your twitter account and enable text message notifications for direct messages (and/or tweets, but I prefer DMs).
(C) Software Configuration
I posted my code, webpage and database template on the project’s github page, github.com/ankitrasto/aetms These can be used as the template for polling temperatures and as the webpage interface.
- Download and extract the contents of the entire git repository to the raspberry pi via git or wget. I’m using wget:
wget https://github.com/ankitrasto/aetms/archive/master.zip unzip master.zip
- When the Apache web server packages were installed, it usually starts running on its own and is accessible by pointing any browser on the pi’s local network to the pi’s IP address. The directory containing these webpages is at /var/www/html. Do the following using the cp and mv commands (you will need to be root or use sudo):
- copy the contents of the github repository’s html directory to the /var/www/html folder.
- delete or rename the index.html file in /var/www/html to something else; this will allow the webserver to point to index.php by default
- copy the contents of the github repository’s cgi-bin directory to the /usr/lib/cgi-bin folder; this contains the python code to poll temperatures and modify the database
- run the a2enmod command to enable CGI/PHP and then restart the apache2 service:
sudo a2enmod cgid php5 sudo service apache2 stop sudo service apache2 start
- move the templogDB.db file from the/var/www/html up one level to /var/www/ (the python code references the database at this location).
- We need to do some ownership changes with the chown command and the user www-data; let www-data take ownership of the directory and all files/subdirectories in both /var/www and /usr/lib/cgi-bin (except the notify.py script):
sudo chown -R www-data:www-data /var/www sudo chown -R www-data:www-data /usr/lib/cgi-binsudo chown pi:pi /usr/lib/cgi-bin/notify.py
this will allow us to use our code and update the webpages without running into permissions issues, and also allow us to use our twitter/mail accounts configured for the user pi as described in section B.
- Navigate to your pi’s web address using another locally networked computer (or on the pi itself) to ensure that you get a webpage, and execute the script therm.py in the /usr/lib/cgi-bin directory to see if you can get a temperature reading that is then appropriately stored in the pi and uploaded to the webserver.
- You will need to make a few changes to the python code in /usr/lib/cgi-bin; change the variable contents of notify.py to coincide with your own email address/twitter handle, as well as the numerical warning thresholds which trigger warnings or critical events.
(C) Cronjobs and Webserver Configurations
Almost there! Now we add automatic scheduling via cron (read about cron) for notify.py and therm.py in /usr/lib/cgi-bin. However, given that both notify and therm have different user permissions and owners, we need to edit the crontab for both users:
- run the crontab editor (I used nano as my default text editor, if asked) for www-data and the therm.py script:
sudo -u www-data crontab -e
and add the following entry to have the therm.py script run every 30 minutes (i.e. temperature is polled every 30 minutes and logged to the database):
*/30 * * * * python /usr/lib/cgi-bin/therm.py
and then save your changes and exit.
- Now, run the crontab editor for the pi user (you) and the notify.py script
- and add the following entry to have notify.py run every 30 minutes as well; note that I added a sleep command before the notify script runs to allow time for the therm.py script to finish executing:
*/30 * * * * sleep 15 && python /usr/lib/cgi-bin/notify.py.
- That should be it! Note however that the web-interface has appropriate PHP code but the interface/graphics/etc. were set up for the quality improvement project for a specific clinic. You will likely need to modify the html code and graphics to suit your own needs. Also note that the PHP code also defines conditional formatting based on warning/critical limits; this should also be modified to your needs
- Also notice that there are multiple probes that can be selected for multiple fridges within a clinic; this is a work in progress, but the idea is to have other individual raspberry pi’s collect their own temperatures and store it into a local database which is then rsynced over ssh to a single raspberry pi which acts as a web server and notification service.