You may not have known it, but you were already using functions in Chapter 5. They were all part of Python’s basic set of functions or in Adafruit’s BeagleBone IO Python Library. For instance, the line of code GPIO.setup("P8_12", GPIO.OUT) calls a function written by Adafruit to make it easy to set pin 12 on header P8 as an output pin. There are a few steps involved in setting the mode of a GPIO pin and therefore a few lines of code. Adafruit’s library makes it easy for us to do it in just one line of code. Writing your own function is actually pretty easy as seen in Example 6-1.

def greet(name): 
        print "Hello, " + name + "! Welcome to my Python script!" 

greet("Andrew") 

When you put the code from Example 6-1 into a file and execute it, you should see the greeting printed. Try calling greet() multiple times with different names in the same script. You’ll see that you can to reuse the same code with different names quite easily.

All function definitions start with the keyword def and then the name of the function that you want to make. Inside the parentheses, you can name each of the parameters, or inputs, that you want the function to take. In the example above, the function greet takes a single parameter, name. Within the function, we can use that parameter’s value by referencing it like we do in the print statement.

Let’s get started writing the function that takes care of sending an email. We can test this function by itself, before getting into working on the physical side of the project. It’s a good idea to compartmentalize the different parts of your project and be able to test them individually before connecting them all together.

You’ll need to find the details of your mail provider’s SMTP server, which is what you connect to in order to send email. Since Gmail is a popular email service, I included their server name in Example 6-2. The code below is based on the examples found on Python’s site. Create a file called emailer.py and put the code from Example 6-2 in it (see Figure 6-1 for a visual representation).

import smtplib 
from email.mime.text import MIMEText 

def alertMe(subject, body): 
        myAddress = "[email protected]" 
        msg = MIMEText(body) 
        msg['Subject'] = subject 
        msg['From'] = myAddress 
        msg['Reply-to'] = myAddress 
        msg['To'] = myAddress 

        server = smtplib.SMTP('smtp.gmail.com',587) 
        server.starttls() 
        server.login(myAddress,'my_password') 
        server.sendmail(myAddress,myAddress,msg.as_string()) 
        server.quit() 

alertMe("Alert!", "Garage door is open!") 

Figure 6-1. The alertMe function in Example 6-2 takes a subject and a body as inputs and connects to the email server to send the message.

If you execute emailer.py (you can run it with the command python emailer.py) and don’t see any errors, check your email for the alert. If you have it, you know you have a working function that you can execute within your code to send you any kind of email alert you’d like. If you’re having trouble, double check your provider’s email settings.

After you’ve got it working, remove the test line alertMe("Alert!", "Garage door is open!") and save the file. Now this function definition can be imported into other Python files as long as emailer.py is in the same directory.

Now that you have the email part of the project working, it’s time to work on the physical side. Detecting whether or not a door is open is pretty simple. A door security sensor will act like a digital switch and can connect directly to the BeagleBone. These sensors can be found in a hardware store or in your local RadioShack.

The sensors typically come in two varieties: normally open (denoted N/O) or normally closed (denoted N/C). A normally open sensor will disconnect the two terminals when the door is opened and the sensor is separated from the magnet. Conversely, a normally closed sensor will connect the two terminals when the door is opened. Some door sensors will work both ways and will have a common terminal, a normally open terminal, and a normally closed terminal, like the one in Figure 6-2. Any version will work in this project because we can use code to check for either a high or low signal.

Figure 6-2. This door sensor has a normally open and a normally closed terminal.

For the code below, I’ll be using a normally closed sensor so that an open door will send a high signal and closed door will send a low signal. In the code, I will indicate where the logic should be changed in case you have a normally closed sensor.

Figure 6-3. Wiring the door sensor to pin 11 on header P8 with a 10K pull-down resistor.

It can be a bit confusing when you start working with lots of nested loops and if statements, so let’s first map out the logic in pseudocode, a way of using plain language to describe what code is going to do.

The main loop constantly checks if the door has been opened. When it senses that the door has gone from being closed to being opened, it saves a time value into alertTime. That time is 60 seconds in the future. For every subsequent check, if the door is still opened, it checks if 60 seconds has passed. If so, it sends an email alert. If the door has been closed, it clears the value of alertTime, ensuring that the next time the door is open, it will start tracking a full 60 seconds again.

There’s also a loop after the email alert is sent to ensure that only a single email is sent if the door has been open for more than a minute. Example 6-3 shows how that logic is converted into Python.

import time
import Adafruit_BBIO.GPIO as GPIO
from emailer import alertMe 

GPIO.setup("P8_11", GPIO.IN)

alertTime = 0 

while True:
   if GPIO.input("P8_11"): 
      if alertTime == 0: 
         alertTime = time.time() + 60 
         print "Door opened. Alerting in 60 seconds if left open."
      else: 
         if time.time() > alertTime: 
            alertMe("Alert!", "The door has been left open!") 
            print "Door has been open for 60 seconds. Sent email alert!"
            while GPIO.input("P8_11"): 
               time.sleep(.1)
   else:
      alertTime = 0 
   time.sleep(.01)

The doorAlert.py file must be in the same directory as emailer.py in order to import the alertMe function from that file.

Next you’ll want to set up doorAlert.py to execute in the background after your BeagleBone starts up. If you want to do that now, jump ahead to Appendix B.

For this project, you’ll use the Flask framework for Python to serve the web page. And since you’re still working in Python, you’ll continue to use Adafruit’s BeagleBone IO Python Library. Before you get into creating your own dynamic site, you’ll have to install Flask and its dependencies using pip:

root@beaglebone:~# pip install flask

To test out Flask, you’ll create a simple web server that replies “Hello, world!” to the request it receives. Start by creating a new file called hello-flask.py with the code from Example 6-4.

from flask import Flask 
app = Flask(__name__) 

@app.route("/") 
def hello():
   return "Hello, world!" 

if __name__ == "__main__": 
   app.run(host='0.0.0.0', port=81, debug=True) 

After saving hello-flask.py and executing it, you should see the following on the terminal:

root@beaglebone:~# python hello-flask.py
 * Running on http://0.0.0.0:81/
 * Restarting with reloader

Then try opening your web browser and navigating to http://beaglebone.local:81. If everything worked, you should see “Hello, world!” in your browser window. If you look back at your BeagleBone terminal, you’ll see the following:

10.0.1.5 - - [16/Jul/2013 12:32:20] "GET / HTTP/1.1" 200 -
10.0.1.5 - - [16/Jul/2013 12:32:20] "GET /favicon.ico HTTP/1.1" 404 -

The first line represents the GET request from the browser for /. The server responded with a code 200, which means OK. This response appeared when the text “Hello, world!” was transmitted to the browser. The second line is another GET request for /favicon.ico, to which the server responded with code 404, meaning “file not found”. Browsers request a small graphic icon when visiting a site to represent it in the location bar and in the bookmarks menu. Your site does not have a favicon.ico file, so you can ignore this error. It won’t cause any problems.

To terminate the server and get back to the command line, type Control-C.

Example 6-4 sent only text to the web browser, none of the HTML formatting that you’d normally expect from a web page. You could write the code yourself to send this formatting along with the return statement in that example, but including all that code in the Python script would get unwieldy very quickly. Luckily for us, Flask uses a template engine called Jinja2, which takes care of combining HTML formatting with the data that our application will provide.

With the capabilities of Jinja2, you can create HTML files that have placeholders for data that comes from our web application. This means that the code that controls the look of the page is kept separate from the actual logic of the application. Flask’s render_template function will take in the data and HTML template filename, pass it to Jinja2, which will return the properly formatted HTML to Flask to return to the user.

To try it out yourself, create a new file called flask-template.py and place the code from Example 6-5 in it. Then create a subdirectory called templates and create a file in there called main.html. Use Example 6-6 as the contents for that file.

from flask import Flask, render_template 
app = Flask(__name__)
import datetime

@app.route("/")
def hello():
        now = datetime.datetime.now()  
        timeString = now.strftime("%Y-%m-%d %H:%M") 
        templateData = {
                'title': 'Hello!',
                'time': timeString
        } 
        return render_template('main.html', **templateData) 

if __name__ == "__main__":
        app.run(host='0.0.0.0', port=81, debug=True)

<!DOCTYPE html>
<head>
<title>{{title}}</title> 
</head>

<body>
<h1>Hello, world!</h1>
<h2>The date and time on the server is: {{ time }}.</h2> 
</body>
</html>

In Example 6-5, the line that says return render_template('main.html', **templateData) instructs Flask to use the Jinja2 template engine to prepare the page. It will look in the folder templates and find the specified file, in this case, main.html. Flask also gives Jinja2 the values stored in the dictionary templateData, which was created a few lines above. These values can be placed in the template by name in between two curly braces, as you see in Example 6-6.

After saving flask-template.py and templates/main.html, execute the script from the command line:

root@beaglebone:~# python flask-template.py
 * Running on http://0.0.0.0:81/
 * Restarting with reloader

Now when you navigate to to http://beaglebone.local:81, you should see the BeagleBone’s time in the browser.

Using the same circuit that you did in The Door Sensor, you can create a web interface with Flask to check the status of the door (see Examples 6-7 and 6-8). Every time a request is made from the server, it will check the state of the GPIO pin and pass “open” or “closed” strings into the template, which is then sent to the browser making the request.

from flask import Flask, render_template
app = Flask(__name__)
import Adafruit_BBIO.GPIO as GPIO 

GPIO.setup("P8_11", GPIO.IN)

@app.route("/")
def hello():
        if GPIO.input("P8_11"):
                doorStatus = "open" 
        else:
                doorStatus = "closed" 
        templateData = {
                'doorStatus': doorStatus,
        } 
        return render_template('main-door.html', **templateData) 

if __name__ == "__main__":
        app.run(host='0.0.0.0', port=81, debug=True)

<!DOCTYPE html>
<head>
<title>Matt's Apartment</title>
</head>

<body>
<h1>Matt's Apartment</h1>
<h2>The door is {{ doorStatus }}.</h2> 
</body>
</html>

Following the code from Example 6-7, you can use the BeagleBone to host web services for additional digital inputs. You can also use Flask to control digital outputs, pulse the PWM pins, and get readings from analog sensors connected to the analog-to-digital converter.

Another powerful feature of Flask is that it can process variables within URLs. For instance, you can set the brightness of an LED based on what URL you request from your browser. You can set up Flask so that the address http://beaglebone.local:81/ledLevel/100 would set the LED to be fully bright and http://beaglebone.local:81/ledLevel/50 would set it to be half dim. All this can be done with just a little bit of code as shown in Example 6-9.

from flask import Flask, render_template
app = Flask(__name__)
import Adafruit_BBIO.GPIO as GPIO
import Adafruit_BBIO.PWM as PWM

PWM.start("P8_13", 0.0)

@app.route("/")
def hello():
   if GPIO.input("P8_11"):
      doorStatus = "open"
   else:
      doorStatus = "closed"
   templateData = {
      'doorStatus': doorStatus,
   }
   return render_template('main-door.html', **templateData)

@app.route('/ledLevel/<level>') 
def pin_state(level):
   PWM.set_duty_cycle("P8_13", float(level)) 
   return "LED level set to " + level + "."

if __name__ == "__main__":
   app.run(host='0.0.0.0', port=81, debug=True)

After adding the route above to your web application, your server will respond to requests made to http://beaglebone.local:81/ledLevel/50 and will PWM the LED at 50% duty cycle so that it’s dim.

In addition to an Internet-connected BeagleBone, you’ll need the following to prototype this project:

Since it’s an analog sensor, you’ll connect the TMP35 to one of the analog input pins on the BeagleBone. Pin 1 of the TMP35 connects to 3.3 volts, pin 2 connects to analog in at pin 40 on header P9 (or any of the other analog input pins) and pin 3 connects to ground, as shown in Figure 6-5. The TMP35 will output 0.1 to 1.2 volts for temperatures from 10 to 120 degrees Celsius. In fact, the formula to determine the temperature is:

degrees celsius = output voltage in mV / 10

To test the circuit, use the code in Example 6-10 in a new file called tmp35.py.

import Adafruit_BBIO.ADC as ADC
import time

ADC.setup()

while True:
    mV = ADC.read('P9_40') * 1800 
    celsius = mV / 10 
    fahrenheit = (celsius * 9/5) + 32 
    print round(fahrenheit, 1) 
    time.sleep(1)

When you execute this Python script, you should see a Fahrenheit value printed every second. Try warming the sensor with your fingers. The value should go up! Let go and watch the value drop again.

Figure 6-5. Wiring the TMP35 temperature sensor to the analog pin at pin 40 on header P9.

Xively is an Internet of Things platform that takes in data from sensors all over the world and stores that in a database. It can then serve the data via their web interface or via an API for your own applications. It was previously known as Cosm, and before that, Pachube. While it’s possible to configure the BeagleBone to store and serve the data itself, the advantage to using Xively is that you can access the data wherever you have an Internet connection without needing to do any special network configuration.

Additionally, their developer libraries make it very easy to connect to their services in many different programming languages. In this section, you’ll use their Python library to push analog sensor data to Xively.

root@beaglebone:~# pip install xively-python

import Adafruit_BBIO.ADC as ADC
import time
import datetime
import xively
from requests import HTTPError 

api = xively.XivelyAPIClient("API_KEY_HERE") 
feed = api.feeds.get(FEED_ID_HERE) 

ADC.setup()

while True:
    mV = ADC.read('P9_40') * 1800
    celsius = mV / 10
    fahrenheit = (celsius * 9/5) + 32
    fahrenheit = round(fahrenheit, 1)

    now = datetime.datetime.utcnow() 
    feed.datastreams = [
        xively.Datastream(id='office_temp', current_value=fahrenheit, at=now) 
    ]

    try:
        feed.update() 
        print "Value pushed to Xively: " + str(fahrenheit)
    except HTTPError as e: 
            print "Error connecting to Xively: " + str(e)
    time.sleep(20)

Under a single device within Xively, you can also add more channels to send multiple sensor values. After storing a second value from the analog-to-digital converter, add the value to the feed.datastreams list following this pattern:

feed.datastreams = [
  xively.Datastream(id='office_temp', current_value=fahr, at=now),
  xively.Datastream(id='outdoor_temp', current_value=outside_fahr, at=now)
]

As it stands, Example 6-11 will only run when you execute it from the command line and it will stop when you terminate it, when you log out, or when you reboot the BeagleBone. Clearly, this isn’t the desired mode of operation for most projects. To set up this project so that it launches automatically, flip ahead to Appendix B.