BeagleBone For Dummies (2015)

Part IV

Programming with Python

Chapter 10

Experimenting with Python

In this Chapter

Fading an RGB LED using PWM with Adafruit’s Python library

Employing the Python library to read analog inputs

Discovering Python’s capability for web projects by sending emails automatically

Figuring out how you can use functions to use various projects together

Getting acquainted with the powerful communication protocol UART

Chapter 10 covers Python and Adafruit’s BeagleBone Input/Output (BBIO) library, which enables you to control the BeagleBone’s General Purpose Input Output (GPIO) pins in a simple and straightforward manner. In this chapter, you get to know functions that allow you to do more complex and useful tasks.

The chapter starts in the analog world. For outputs you get to see Adafruit’s Python BBIO functions that deal with pulse-width modulation (PWM) by creating a project to fade an RGB LED. For inputs you find out how to measure analog quantities from temperature sensors. You also get to see the ease with which the BeagleBone can interact with the web, and you explore one of the BeagleBone’s communication protocols — UART — that makes data transfer between devices a breeze.

As we preach throughout this book, illustration and practice are great ways to understand and master important digital electronic concepts and the BeagleBone. Gather your tools; it’s wiring time!

Fading an RGB LED with Python

Light-emitting diodes (LEDs) are fun. RGB (red-green-blue) LEDs triple the fun with the possibility of creating some sweet color effects with three different colors.

This project consists of controlling which colors of the RGB LED are on and how bright they are through the use of pulse-width modulation (PWM) and Adafruit’s BeagleBone I/O Python Library.

If you have enough space to set aside the projects in this chapter without unwiring them, we recommend that you keep them intact. Later in the chapter is a section where you mix various projects together.

You need the following components:

· An RGB common cathode LED

· Three 220 Ω or 470 Ω resistors

· A breadboard

· Jumper wires

Wiring an RGB LED

This section assumes that you use an RGB common cathode LED. If you have only a common anode LED, your code and your wiring has to be slightly different from what is illustrated in the following sections. See Chapter 8for a description of RGB common cathode LEDs and RGB common anode LEDs.

The wiring for this project is exactly the same as the wiring for the RGB project in Chapter 8, but the project itself is quite different.

To wire everything together, follow these steps:

1. Use a jumper to connect P9_14 to a vertical row on your breadboard.

This pin is the one you use to control the red color of your RGB LED.

2. Use a jumper to connect P9_16 to a vertical row on your breadboard.

This pin is the one you use to control the green color of your RGB LED.

3. Use a jumper to connect P8_13 to a vertical row on your breadboard.

This pin is the one you use to control the blue color of your RGB LED.

Use color coding to keep yourself organized. In this scenario, using red jumper wires for P9_14, green jumper wires for P9_16, and blue jumper wires for P8_13 probably would be a good idea.

4. To each of these jumpers, wire a 220 Ω or 470 Ω resistor.

5. Wire the longer lead of your RGB LED to ground (GND) on the breadboard rail.

Figure 10-1 illustrates the correct wiring.

Trimming the long lead might make it easier to plug the RGB LED into the breadboard. If you do that, you can distinguish the GND lead by looking at the LED’s lens. The biggest chunk of lead inside the lens corresponds to the GND lead.

Figure 10-1: RGB wired to BeagleBone Black.

You can use eight pins as PWM pins. Read Chapter 6 for more information about the PWM pins.

Writing the code for fading an RGB LED

Create a script named RGB.py, and type the following:

#!/usr/bin/python
import Adafruit_BBIO.PWM as PWM
import time

RGB = ["P9_14", "P9_16", "P8_13"]
#RGB[0] controls red, RGB[1] controls green, RGB[2]controls blue

for i in range(0, 3): #runs the indented code below 3 times
PWM.start(RGB[i], 0) #initialize PWM with all leads OFF

#set initial conditions
c_initial = RGB[0]
c_next = RGB[1]
c_off = RGB[2]

while True:
PWM.set_duty_cycle(c_off, 0)
for i in range(0, 100):
PWM.set_duty_cycle(c_initial, 100-i)
PWM.set_duty_cycle(c_next, i)
time.sleep(0.05) #change this line for faster/slower fading speed
#swap the colors in the following order: R->G->B->Repeat
aux = c_initial
c_off = c_next
c_next = c_off
c_off = aux

The following sections break down the code for easier understanding.

Importing libraries

The first step after the shebang in a Python script is importing libraries. In this case, you want to import Adafruit’s library and define a PWM object, which you name PWM:

import Adafruit_BBIO.PWM as PWM
import time

Then you import the time library, which we cover in Chapter 9. This library enables you to halt the program for a set number of seconds, using the sleep() function:

Initializing PWM and setting initial conditions

The following chunk of code contains two Python concepts: lists and for loops:

RGB = ["P9_14", "P9_16", "P8_13"]
#RGB[0] controls red, RGB[1] controls green, RGB[2]controls blue

for i in range(0, 3): #runs the indented code below 3 times
PWM.start(RGB[i], 0) #initialize PWM with all leads OFF

A list is a compound data type. It’s a group of variables. Within a list, you can save more than one value. In this case, you create a list called RGB where you save the pins that are used in this project. You can access each individual value within a list by using a subscript. In this case, RGB[0] refers to "P9_14", RGB[1] refers to "P9_16", and RGB[2] refers to "P8_13". You can use each element of a list the same way that you use a regular variable.

In Python, the subscript that refers to the first element of a list is always 0, not 1.

You can use lists that consist of both text (strings) and numeric values, such as someList = [1, "hello" 35.117, 141, "bye"]. It’s often advisable, however, for a list to hold items of the same type.

Next comes the for loop:

for i in range(0, 3): #runs the indented code below 3 times
PWM.start(RGB[i], 0) #initialize PWM with all leads OFF

for loops are of extreme importance in the world of programming because they enable you to do stuff a set number of times while increasing a variable in every iteration of the code.

The code after this for loop runs three times, but it isn’t always exactly the same code. Because the variable i increases by 1 at each iteration, this loop goes through all elements of the RGB list and runs the function PWM.start(pin, duty) on each of them:

PWM.start(pin, duty)

This function takes two parameters:

· pin: The pin that you want to use as PWM.

· duty: The initial duty cycle, which goes from 0 for off to 100 for maximum.

Chapter 6 explains that the BeagleBone’s PWM default polarity is HIGH, which is somewhat counterintuitive. In the situation described in Chapter 6, the duty-cycle period is a period in which the voltage is LOW, so by default, setting a higher duty cycle on a BeagleBone PWM pin means a LOW voltage. Adafruit’s Python library (and BoneScript) functions work in reverse; the default polarity becomes LOW, so the duty cycle is a period in which the voltage is HIGH.

The default might be different on your BeagleBone, and the functions of the libraries you are using might be of a different version that changed these defaults. That said, if things don’t work properly, you may have to reverse all the parts of the code that deal with PWM such that a higher duty cycle means lower brightness (100 is off and 0 is maximum).

Last, you define the initial conditions for the leads of your RGB LED:

#set initial conditions
c_initial = RGB[0]
c_next = RGB[1]
c_off = RGB[2]

Red is the first color, green is the second, and blue is off initially. Naturally, you can change this order as you want. You can also have the three colors on at the same time for different color effects.

Fading from one color to the next

For the while that loops forever, you start by turning one of the lights off; blue is defined as the one that stays off initially. Thus, you set the duty cycle of the PWM that controls blue to 0. Then you have a for loop that increments i from 0 to 100 in intervals of 0.05 seconds, increasing c_next’s duty cycle with i while c_initial’s decreases. This loop makes the RGB LED continually fade from c_initial (initially red) to c_next(initially green). The following snippet of code is responsible for that:

while True:
PWM.set_duty_cycle(c_off, 0)
for i in range(0, 100):
PWM.set_duty_cycle(c_initial, 100-i)
PWM.set_duty_cycle(c_next, i)
time.sleep(0.05) #change this line for faster/slower fading speed

Swapping the variables

Because you want the same code to run over and over with different colors and succession, this part of the code swaps the values of the variables around:

#swap the colors in the following order: R->G->B->Repeat
aux = c_initial
c_initial = c_next
c_next = c_off
c_off = aux

c_initial gets the value within c_next; c_next gets c_off; and c_off gets c_initial. An auxiliary variable named aux is used so that you don’t lose the value within c_initial when swapping the values.

Running the script for fading an RGB LED

Save the script, run it, and watch the show! Mess around with your code to see the LED fading faster, slower, and in a different order. Change the way duty cycles vary, and combine the three colors in different ways to create cool light effects.

If your circuit doesn’t work, you might need to troubleshoot it with a multimeter. Check www.dummies.com/extras/beaglebone to see how to do so.

If the LED is too dim, use a 220 Ω resistor rather than a 470 Ω resistor.

Working with Analog Sensors

Analog sensors measure many types of useful data, such as temperature, humidity, light, and distance. The simplest analog sensors work by outputting a voltage that depends on the data they measure. This relationship is often listed on the datasheet of the device as a mathematical formula or a graphical representation.

You work with different sensors in similar ways, as demonstrated by the two examples in the next sections. All you have to do is connect the sensor to one of the BeagleBone’s analog-to-digital converter (ADC) pins and read its voltage. Sometimes, there may be a difference in wiring, but the greatest difference is in the calculation that relates voltage to the data that the sensor measures. Figure 10-2 shows which of the BeagleBone’s pins can be used as analog inputs; they’re labeled from AIN0 to AIN6.

You need the following components:

· Temperature sensor: TMP36

· Infrared (IR) distance sensor: Sharp GP2Y0A21YK

· Two 10K Ω resistors

· A breadboard

· Jumper wires

Figure 10-2: BeagleBone GPIOs with the ADC pins.

If you can read and understand the important information in a datasheet, you should be able to use any other sensors by using the concepts shown in this section.

Using the right voltage for the ADC

The following information is so important that the section is one big Warning. Take heed!

Feeding a voltage higher than 1.8V to an ADC pin of the BeagleBone may be hazardous to your board. This situation is something of a nuisance, because most sensors output voltages up to 3.3V, which means that you can’t connect them to the ADC immediately. You need a circuit consisting of two resistances to eat up the extra voltage (see Figure 10-3). This circuit is called a voltage divider.

Because the ADC pin is in parallel to one of the resistances, it has the same voltage. When you have two resistors in series, the voltage dropped along one of them is the following:

Figure 10-3: Voltage-divider circuit.

The voltage on the resistor is the ratio of the total resistance. Using two equal resistors means that the ADC has 50 percent of the total voltage. If you’re dealing with 3.3V, half is 1.65V, which gives you a little leeway. Two 10K Ω resistors should do the trick. Don’t use resistors with smaller values!

If you use sensors that output a higher maximum voltage level, it’s imperative to determine the ratio of the resistances that you use. For a sensor that outputs 5V, for example, you have the following:

In this case, you should use a pair of resistors where the resistor that is in parallel with the ADC has to have at most 36 percent of the total resistance. You should use a value slightly smaller than the one calculated to have some leeway. A 10K Ω and a 22K Ω resistor achieve a ratio of 31.25 percent, which works just fine by setting the maximum voltage to 1.5625V.

Due to the imprecision of resistors, these values are always slightly different. That’s why it’s important to calculate for slightly less than 1.8V so that you have some safety margin.

Wiring an IR distance sensor

The IR sensor we use for this project is the Sharp GP2Y0A21YK (see Figure 10-4), due to the fact that it’s quite popular and easy to acquire. If you use another sensor, you should consult its datasheet to see which of its pins are GND (ground), Vcc (supply voltage), and Vo or Vout(output voltage). You also need to find the mathematical or graphical relationship between voltage and distance, which affects the last calculation in the code.

Figure 10-4: IR distance sensor: Sharp GP2Y0A21YK.

Follow these steps to prepare your breadboard to wire up the IR distance sensor Sharp GP2Y0A21YK:

1. Use a jumper to connect GND — P9_1, P9_2, P8_1, or P8_2 — to a horizontal track on your breadboard.

2. Use a jumper to connect 5V to another horizontal track on your breadboard.

Use P9_7 and P9_8 if you are powering the BeagleBone via USB and use P9_5 and P9_6 if you are powering it through an external voltage source.

3. Use a jumper to connect P9_40 to a vertical row on the breadboard.

This pin is the one that will read the analog input: AIN 1.

4. Divide the voltage by connecting two 10K Ω resistors to the jumper that comes from P9_40.

One resistor should connect to GND, and the other should connect to the output voltage that comes from the sensor.

To wire up the sensor, you need to know its pinout, which you can find on the datasheet. For the Sharp sensor we’re using for this project, refer to Table 10-1. The position described in the table is based on the connectors pointing toward you.

Table 10-1 Pinout of IR Distance Sensor Sharp GP2Y0A21YK

Follow these steps to connect the pins to the jumpers you pulled from the BeagleBone (see Figure 10-5):

1. Connect pin 1 of the IR sensor to the resistor that connects to P9_40.

2. Connect pin 2 of the IR sensor to GND.

3. Connect pin 3 of the IR sensor to 5V.

Figure 10-5: IR distance sensor wired to BeagleBone Black with a voltage divider.

Writing the code to measure distance

Create a script named IR.py, and type the following code:

#!/usr/bin/python
import Adafruit_BBIO.ADC as ADC
import time
import math

sensor = "P9_40" #or AIN1

ADC.setup()

while True:
reading = ADC.read(sensor) # values from 0 to 1
voltage = reading * 1.65 #values from 0 to 1.65V
distance = 13.93 * pow(voltage, -1.15)
if distance > 80:
print("Can't measure more than 80cm!")
else:
print("The reading, voltage and distance (in cm) are " + str(reading), str(voltage), str(distance))
time.sleep(0.05) #loop every 50 milliseconds.

This code is quite straightforward: It imports an object as ADC to access the ADC pins on the BeagleBone. A new library joins the fray: math. This library includes several functions that simplify complex calculations.

A variable named sensor defines the analog pin to be used, and you use ADC.setup(), which always needs to be present in a program before it starts reading from the ADCs.

You can write AIN0-6 in place of P9_33-40. Note, though, that the order of the numbering of the AINs does not correspond to the numbering of the P9 header: AIN4 is P9_33, and AIN5 is P9_36, for example. Refer to Figure 10-2 earlier in this chapter whenever you’re in doubt.

Then comes the while True: loop. The program reads the value of the ADC, which goes from 0 to 1 and represents the fraction of the voltage that’s read on the pin. Because that voltage always goes from 0 to 1.65, simply multiplying the reading by 1.65 gets you the real value.

Getting the actual voltage value isn’t necessary in many applications. In fact, working with percentages may be much easier.

You convert the voltage reading to the distance in centimeters. This calculation depends on the sensor you use. The pow() function is imported from the math library and calculates voltage to the power of -1.15. It works as follows:

result = pow(base, exponent)

This function has three variables:

· base: The number you want to elevate to the power of the exponent

· exponent: The exponent’s value

· result: The variable where the result will be saved

Python can make that calculation without resorting to functions, but the process is a bit messy and prone to bugs. Also, introducing the math library seems like a good idea, as the library features many other useful mathematical functions, such as sine(), cosine(), and root(). Your program would also work with voltage**-1.15 instead.

Sharp’s sensor datasheet provides only a graphical representation to convert voltage into distance, so the formula used in the example is a made-up workaround, which means the following:

· It isn’t 100 percent accurate.

· The graphic shows that some distances less than 6cm read the same voltage as distances greater than 6cm. Thus, this formula works only for distances greater than 6 cm.

· The 6cm distance is theoretical. In reality, this value will most likely be different — both because the sensor isn’t perfect and because you’re using a voltage divider. You can (and should) test what’s truly the minimum distance after you run the script.

At the end, you simply print everything and make the program sleep for 0.05 second after each iteration so as to not overburden the central processing unit (CPU).

If you can’t find the mathematical relationship for a given graphic, don’t fret. You can simply write a program consisting of intervals and if statements. For this project, if you check the IR’s datasheet, you see that a sensor output of 1V and 1.5V means a distance between ~15 cm and ~25 cm. Thus, you could create a program that works in the following fashion:

if distance > 15 and distance <= 25
do_something()
elif distance > 25 and distance <= 35
do_something_else()
#and so on so forth

Normally, though, it’s easy to find a mathematical relationship. If you don't see it on the datasheet, try an Internet search.

Running the script to measure distance

Save your script by pressing F5 or clicking Run. Move your hand or any other object close to and farther from your sensor to see that the values printed on your screen reflect different distance readings.

Play around with the IR sensor by moving an object very close to it — somewhere between 5cm and 15cm — and use a ruler to check the practical minimum value of distance that you read. This value will be useful in future programs. For us, the distance was a little bit over 9cm, so that’s the value we use as minimum.

Wiring a temperature sensor

The wiring for this project is simple. Start by checking your temperature sensor’s datasheet to see its pinout. If you’re using the TMP36 and looking at it from below, with the curved side facing you, you can refer to Table 10-2.

Table 10-2 Pinout of the Temperature Sensor TMP36

The sensor we used in the example doesn’t require a voltage divider because its output surpasses 1.8V only for 266 degrees F (130 degrees C). If the one you use surpasses that voltage at a much lower temperature — or if you’re afraid that the TMP36 will read more than 266 degrees F — simply employ a voltage divider as described in the “Using the right voltage for the ADC” section. You can wire it to your circuit exactly as described in the “Writing the code to measure distance” section.

Follow these steps to wire your temperature sensor:

1. Connect the BeagleBone’s GND — pin P9_1, P9_2, P8_1, or P9_2 — to the sensor’s GND.

2. Connect the BeagleBone’s 3.3V supply — pins P9_3 and P9_4 — to the sensor’s Vcc.

3. Connect the BeagleBone’s AIN0 — pin P9_39 — to the sensor’s Vout (output).

Figure 10-6 shows a circuit diagram for this circuit.

Figure 10-6: Temperature sensor wired to BeagleBone Black.

Writing the code to read temperature

As we mention earlier in this chapter, the code you use to read from a sensor is always similar regardless of the type of sensor. The only important differences between this code and the code in the “Writing the code to measure distance” section are the calculations that give the temperature in different units. Refer to “Wiring an IR distance sensor” earlier in this section for a discussion of the code that deals with analog inputs.

To have your BeagleBone print the temperature values that the sensor reads, type the following code:

import Adafruit_BBIO.ADC as ADC
import time

sensor = "P9_39"

ADC.setup()

while True:
reading = ADC.read(sensor) # values from 0 to 1
voltage = reading * 3.3 #values from 0 to 3.3V, although this only surpasses 1.8V for temperatures over 266 degrees F

# the voltage/temperature relationship is as follows:
# Vo = 1/100 * Temperature + 0.5
temperatureC = (voltage - 0.5) * 100
temperatureF = (temperatureC * 9/5) + 32

print("The reading is: " + str(reading) + "which is, in Volts: " + str(voltage))
print("The temperature in Celsius is: " + str(temperatureC) + "; and in Fahrenheit: " + str(temperatureF))
time.sleep(0.05) #loop every 50 milliseconds.

Running the script to read temperature

Save and run your script, and watch your readings fill the screen. Touch your sensor with your finger, and notice that the values increase. If it’s chilly outside, and you’re using a laptop, take your circuit for a walk and see the values decreasing. The sensor should detect the temperature quickly.

Simply reading from sensors is fun, but getting stuff running based on readings is what the buzz is all about. Don’t unwire this circuit from your breadboard just yet. You use it in another project later in this chapter.