Introduction: Raspberry Pi Home Monitoring With Dropbox
This tutorial will show you how to create a simple and expandable home monitoring system using a Raspberry Pi, a webcam, a few electrical components and your Dropbox account. The finished system will allow you to remotely request and view images from your webcam while also using an off-the-shelf digital temperature sensor to monitor the temperature of your home over the internet, all using Dropbox.
This was the first project I thought up after receiving a Raspberry Pi 2 model B. My aim was to create a Python-based monitoring system that I could control and receive data from over the internet. While there are many different ways of doing this, I decided to use Dropbox as the interface between the Pi and the internet as they have a simple Python API which allows you to upload, modify and search for files in specific folders using a few lines of code.
I also wanted my solution to be lightweight and simple, and to avoid cluttering my Pi with unnecessary libraries and programs. The software component of this project consists of a single Python script, meaning that you can continue to use your Pi as normal, even when the monitoring system is running.
For this project you will need:
- A Raspberry Pi. Any model should work, I used a Pi 2 model B starter kit, but perhaps you need the central unit only.
- A USB webcam. I bought a cheap ADVENT AWC72015, which happened to work fine. It may be a good idea to consult this list of webcams which are confirmed to work with the Pi. Note that some require a powered USB hub (mine works fine without).
- A Dropbox account. I use my standard free account as this project does not require much storage space.
- A DS18B20 digital temperature sensor and a 4.7k resistor. You can buy both from here, but they are widely available from many electronics websites.
- Some circuit-building accessories. I'd recommend using a breadboard and some jumper cables to make the circuit building process as easy as possible.
[If you decide to buy any of these products, I would greatly appreciate it if you access the listings using the above links - that way, I get a tiny share of the profits at no extra cost to you!]
Step 1: Set Up the Hardware
The first step is to ensure that your Pi and the associated peripherals are set up.
First, connect your Pi to the internet. This is necessary to ensure that the monitoring program can receive your requests and upload data to Dropbox. I use an ethernet connection to ensure reliability, but a Wi-Fi connection should work fine too, while also having the advantage of improved portability. If you choose Wi-Fi, I'd recommend this USB dongle for the Pi.
Next, connect your webcam to the Pi by plugging it into one of the USB ports. While my Advent webcam's instructions did not explicitly say that it would work with Linux, all I had to do was plug it in and boot up the Pi. No further installation was needed. Other webcams may vary. You can check whether your webcam has been detected by Linux using the following command:
In the above image, my webcam is listed as '0c45:6340 Microdia'
Finally, you can connect your DS18B20 temperature sensor to the Pi's GPIO header. I use my breadboard to make the process of creating circuits easier, and I'd recommend you do the same, especially as the DS18B20 requires a 4.7k resistor to be placed between two of its three pins. This link provides a good wiring diagram showing how a breadboard can be used to connect to this temperature sensor.
The next page of the above tutorial also covers the steps needed to read data in from the DS18B20, and shows you how to check that it is working. It is important to perform these setup steps before you can use the DS18B20 for this project. We will also be integrating the sample Python script from the tutorial into our monitoring program, so you may want to have a quick skim over this code.
Please also make note of your DS18B20's unique number. It is the number beginning with '28-' that you come across during the setup tutorial. You will need to enter it into the upcoming Python program to allow it to read in the temperature.
Step 2: Set Up Dropbox
In order for your Pi to interface with Dropbox, you need to set up a new Dropbox app. This will provide you with details needed for your Pi to perform online file management using Python. Assuming you have created a Dropbox account and logged in, you can create a new app using the 'Developers' menu option. See the above image for a summary of the important steps.
Within the 'Developers' menu, select 'My apps', then press the 'Create app' button. To fill out the resulting form, select 'Dropbox API' followed by 'App Folder'. Finally, you can choose a unique name for your app within Dropbox. Click 'Create app'.
You will then be taken to your app's settings page within Dropbox. There is only one further thing you need to do here - generate yourself an Access Token. To do this, scroll down to the 'OAuth 2' section and under 'Generated access token', click the 'Generate' button.
This will present you with a long string of characters which are needed to access your Dropbox account using Python. Make a note of this Access Token as you will need to specify it later in your code. If you lose the token, you can navigate back to your app's settings by clicking 'My apps' in the Dropbox 'Developers' section and generate a new token.
You can leave the other settings as they are. To confirm that your app has created the necessary folders on your Dropbox account, navigate to your storage homepage and look for the 'Apps' folder. Within this folder should be a sub-folder with the name you chose for your new app. This is where all files for your monitoring system will be placed.
Step 3: Preparing Your Dropbox App Folder
Once you have set up your Dropbox app, it's time to think about how you will use the resulting folder in your Dropbox account to interact with your Pi. This is accomplished quite simply. The Python script which will run on the Pi will use a subset of commands from the Dropbox API to search and modify the names of some empty, extension-less files in your app folder. We will call these files 'parameter files' as each one will allow you to control a different aspect of the monitoring system's behaviour. The image above shows the four parameter files which need to be present in your Dropbox app folder for this project. Creating them is simple:
Starting with your app folder completely empty, open a text editor program on your computer. While this could be done using the Pi, I found it easier to use my Windows laptop for this setup phase. Once the text editor is open (I used Notepad on Windows 7), all you need to do is save a completely empty text file anywhere on your computer. As our first example, we will create the first parameter in the header image. Name the file 'delay=10' when you save it.
To recap, you should now have an empty text file stored on your computer with the name 'delay=10'. The file will also have a '.txt' extension which may or may not be visible.
The next step is to upload this file to your Dropbox app folder. This is just like any other Dropbox upload. Simply navigate to your app's folder and click 'Upload' and choose your 'delay=10' file.
When this file has uploaded, you must remove the '.txt' extension which should now be visible in the filename. To do this, simply right click the file and select 'Rename'. Remove the '.txt' part of the filename. You should now be left with a file called 'delay=10' with no file extension, as shown in the header image.
The 'delay' parameter file is one of four which will be used by the monitoring program. To create the others, you can just copy and rename your 'delay' file by right clicking it. Once you have created three copies, name them as shown in the header image so that your app folder is identical to that shown at the beginning of this step.
Step 4: Getting Started With the Code
As discussed, the core of our monitoring system will consist of a single Python script which will interface with Dropbox. In order for the monitoring program to be active, this script will have to run in the background on your Pi. I guess it is most accurately described as a 'daemon' script, meaning you can just set it running and forget about it. The script is attached to this step, so there is no sense in repeating the code here. Now may be a good time to download it and familiarise yourself with it.
Before you will be able to run the script, it is important to ensure you have the relevant Python libraries installed. The ones you need are listed at the top of the attached script. They are:
import dropbox import pygame.camera import os import time
The Python installation on my Pi already included pygame, os and time so the only one I had to install was Dropbox. I did this using their very simple installation instructions with pip.
Once your libraries are set up, you will need to edit the top two lines of the attached script to match your Dropbox Access Token and your DS18B20 temperature sensor's unique identifier. These are the two lines which need to be edited:
APP_ACCESS_TOKEN = '**********' THERMOMETER_FILE = '/sys/bus/w1/devices/28-**********/w1_slave'
Just replace the ****s with the correct values. At this point, you are actually ready to start using the monitoring program! Instead of just jumping in, I'd recommend that you continue to the next step for a general overview of the code.
IMPORTANT: When you run this script, you want it to run in the background so that a) you can continue to use the Pi, and b) when you close your SSH session, the script will continue to run. This is the command I use when I run the script:
nohup python DropCamTherm.py &
This accomplishes three things: It will run the script ('python DropCamTherm.py'), it will return control to the command line immediately so you can continue to use the Pi ('&'), and it will send Python outputs that would normally be displayed on the command line into a file called 'nohup.out'. This can be read using a Linux text editor (my favourite is nano), and will be created automatically in the directory from which the script is being run.
Step 5: Digging Deeper Into the Code
When you open the script, you will notice that it consists of three functions along with a block of code which implements these functions when the script is run. The functions use the Dropbox API and and access the DS18B20's temperature log file in order to listen for commands from Dropbox and upload the latest temperature reading. Below is an overview of what the functions do, and how they are used to make the monitoring system work:
This function shows the purpose of the Dropbox parameter files we created in step 3. It searches the Dropbox app folder for a file containing the text 'param='. It then extracts the text after the '=' and tries to convert it into an integer. You can see that this allows us to control the program by appending relevant numbers to the end of the parameter files manually. The next step will contain a brief instruction manual showing you how to use each of the parameter files to control an aspect of the program.
This function allows the program to rename a parameter file from within Python. It does this on a few occasions, mainly to reduce the need for excessive manual renaming of the files.
This function makes use of set_parameter() to upload the latest temperature to the Dropbox app folder by appending it to the 'temperature' parameter file. The function reads the latest temperature from the DS18B20's log file (which is available on Linux at the path pointed by the THERMOMETER_FILE variable).
The final part of the program contains the code which will execute when the script is run. After some setup steps required for the DS18B20 sensor, it opens a Dropbox session using your Access Token and uses pygame to search out your webcam. If a webcam is found, it will enter a loop where it uses poll_parameter() to extract information from Dropbox and act on it.
IMPORTANT: You will notice the following line of code:
cam = pygame.camera.Camera(cam_list, (864, 480))
...this attempts to create a usable camera interface from the first webcam that pygame detects. The resolution may need to be changed to match your webcam. Experiment with a number of values to find what works best.
Step 6: Using the Dropbox Parameter Files
So now you should have a working script which, when run using the instructions from step 4, will allow your Pi to start monitoring the app folder for your inputs. On your first run, the app folder should contain the following parameter files:
delay=10 exitprogram=0 imagerequest=0 temperature=0
Interaction with the program is achieved by manually renaming the parameter files via Dropbox. To do this, just right-click one of the files and select 'rename'. Each parameter file has a different function:
This file tells the monitoring program how many seconds to wait between each iteration of the monitoring loop. When I know that I won't be interacting with the program much, I set it to 60 or 120. When I know that I want to request data from the Pi often, I set it to 10.
This should be set to 1 or 0. If the program detects that it is set to 1, it will end the script. If you set it to 1 and the script exits, you will need to log in to the Pi again to start it back up. This parameter exists so that you can gracefully end the monitoring program when you no longer need it to be running (for example, if you have returned home and no longer want to monitor the webcam remotely).
This is perhaps the most important parameter. This should be set to 1 or 0. If the program detects that it is set to 1, it will request an image from the webcam and upload it into the app folder (with the title 'image.jpg'). If another 'image.jpg' exists, it will overwrite it.
This is the DS18B20 temperature reading set by the set_latest_temp() function. You should never need to edit this parameter file - it is automatically set by the program.
Note that if you set 'exitprogram' or 'imagerequest' to 1, the program will automatically return them to 0 before executing the relevant code. This is for convenience. You may also notice that the code contains a lot of 'try' and 'except' blocks surrounding many of the critical functions. This is to ensure that the script will not throw exceptions (and hence stop running) if something goes wrong (such as an internet connectivity problem preventing Dropbox access).
Step 7: Conclusion
This project has presented a way to control a Raspberry Pi using Python and Dropbox. While the hardware used in this project is a temperature sensor and a USB webcam, there are many other applications for this method of controlling the Pi. In fact, any hardware component that is accessible via GPIO can be controlled using a similar program structure, making the system very easy to expand.
As a next step, you could also use a GUI library such as Tkinter along with the Dropbox API to create a client program which would allow you to modify the parameter files without even needing to log in to Dropbox.
I hope that this tutorial has been clear, and if you have any questions or would like me to clarify anything, please post a comment!