Digital Output: Lighting Up an LED

The easiest way to use outputs with the GPIO pins is by connecting an LED, or light-emitting diode. You can then use the Linux command line to turn the LED on and off. Once you have an understanding of how these commands work, you’re one step closer to having an LED light up to indicate when you have new email, when you need to take an umbrella with you as you leave your house, or when it’s time to go to bed. It’s also very easy to go beyond a basic LED and use a relay to control a lamp on a set schedule, for instance.

Beginner’s Guide to Breadboarding

If you’ve never used a breadboard (Figure 6-4) before, it’s important to know which terminals are connected. In the diagram, we’ve shaded the terminal connections on a typical breadboard. Note that the power buses on the left side are not connected to the power buses on the right side of the breadboard. You’ll have to use male-to-male jumper cables to connect them to each other if you need ground and voltage on both sides of the breadboard.

Figure 6-4. Breadboard

Here are the instructions you should follow:

1. Using a male-to-female jumper wire, connect pin 25 on the Raspberry Pi to the breadboard. Refer to Figure 6-2 for the location of each pin on the Raspberry Pi’s GPIO header.

2. Using another jumper wire, connect the Raspberry Pi’s ground pin to the negative power bus on the breadboard.

3. Now you’re ready to connect the LED (see Figure 6-5). Before you do that, it’s important to know that LEDs are polarized: it matters which of the LED’s wires is connected to what. Of the two leads coming off the LED, the longer one is the anode (or “plus”) and should be connected to a GPIO pin. The shorter lead is the cathode (or “minus”) and should be connected to ground. Another way to tell the difference is by looking from the top. The flat side of the LED indicates the cathode, the side that should be connected to ground. Insert the anode side of the LED into the breadboard in the same channel as the jumper wire from pin 25, which will connect pin 25 to the LED. Insert the cathode side of the LED into the ground power bus.

Note

An easy way to remember the polarity of an LED is that the “plus” lead has had length added to it, while the “minus” lead has had length subtracted from it.

Figure 6-5. Connecting an LED to the Raspberry Pi

4. With your keyboard, mouse, and monitor hooked up, power on your Raspberry Pi and log in. If you’re at a command line, you’re ready to go. If you’re in the X Window environment, double-click the LXTerminal icon on your desktop. This will bring up a terminal window.

5. In order to access the input and output pins from the command line, you’ll need to run the commands as root, the superuser account on the Raspberry Pi. To start running commands as root, type sudo su at the command line and press Enter:

   pi@raspberrypi ~ $ sudo su
   root@raspberrypi:/home/pi#
   

   You’ll notice that the command prompt has changed from $ to #, indicating that you’re now running commands as root.

Warning

The root account has administrative access to all the functions and files on the system and there is very little protecting you from damaging the operating system if you type a command that can harm it.  You must exercise caution when running commands as root. If you do mess something up, don’t worry about it too much; you can always reimage the SD card with a clean Linux install; however, you’ll lose any customization you made to the operating system, as well as any programs or sketches you wrote.

When you’re done working within the root account, type exit to return to working within the pi user account.

6. Before you can use the command line to turn the LED on pin 25 on and off, you need to export the pin to the userspace (in other words, make the pin available for use outside of the confines of the Linux kernel), this way:

   root@raspberrypi:/home/pi# echo 25 > /sys/class/gpio/export
   

   The echo command writes the number of the pin you want to use (25) to the export file, which is located in the folder /sys/class/gpio. When you write pin numbers to this special file, it creates a new directory in /sys/class/gpio that has the control files for the pin. In this case, it created a new directory called /sys/class/gpio/gpio25.

7. Change to that directory with the cd command and list the contents of it with ls:

   root@raspberrypi:/home/pi# cd /sys/class/gpio/gpio25
   root@raspberrypi:/sys/class/gpio/gpio25# ls
   active_low  direction  edge  power  subsystem  uevent  
     value
   

   The command cd stands for “change directory.” It changes the working directory so that you don’t have to type the full path for every file. ls will list the files and folders within that directory. There are two files that you’re going to work with in this directory: direction and value.

8. The direction file is how you’ll set this pin to be an input (like a button) or an output (like an LED). Because you have an LED connected to pin 25 and you want to control it, you’re going to set this pin as an output:

   root@raspberrypi:/sys/class/gpio/gpio25# echo out > 
     direction
   

9. To turn the LED on, you’ll use the echo command again to write the number 1 to the value file:

   root@raspberrypi:/sys/class/gpio/gpio25# echo 1 > value
   

10. After pressing Enter, the LED will turn on! Turning it off is as simple as using echo to write a zero to the value file:

    root@raspberrypi:/sys/class/gpio/gpio25# echo 0 > value
    

So if writing to a file is how you control components that are outputs, how do you check the status of components that are inputs? If you guessed “reading a file,” then you’re absolutely right. Let’s try that now.

Digital Input: Reading a Button

Simple pushbutton switches like the one in Figure 6-6 are great for controlling basic digital input. Best of all, they’re made to fit perfectly into a breadboard.

Figure 6-6. Button

When you read a digital input on a Raspberry Pi, you’re checking to see if the pin is connected to either 3.3 volts or to ground. It’s important to remember that it must be either one or the other, and if you try to read a pin that’s not connected to either 3.3 volts or ground, you’ll get unexpected results. Once you understand how digital input with a pushbutton works, you can start using components like magnetic security switches, arcade joysticks, or even vending machine coin slots. Start by wiring up a switch to read its state:

1. Insert the pushbutton into the breadboard so that its leads straddle the middle channel.

2. Using a jumper wire, connect pin 24 from the Raspberry Pi to one of the top terminals of the button.

3. Connect the 3V3 pin from the Raspberry Pi to the positive power bus on the breadboard.

   Warning

   Be sure that you connect the button to the 3V3 pin and not the 5V pin. Using more than 3.3 volts on an input pin will permanently damage your Raspberry Pi.

4. Connect one of the bottom terminals of the button to the power bus. Now when you push down on the button, the 3.3 volts will be connected to pin 24.

5. Remember what we said about how a digital input must be connected to either 3.3 volts or ground? When you let go of the button, pin 24 isn’t connected to either of those and is therefore floating. This condition will cause unexpected results, so let’s fix that. Use a 10K resistor (labeled with the colored bands: brown, black, orange, and then silver or gold) to connect the input side of the switch to the ground rail, which you connected to the Raspberry Pi’s ground in the output example. When the switch is not pressed, the pin will be connected to ground.

   Electricity always follows the path of least resistance toward ground, so when you press the switch, the 3.3 volts will go toward the Raspberry Pi’s input pin, which has less resistance than the 10K resistor. When everything’s hooked up, it should look like Figure 6-7.

6. Now that the circuit is built, let’s read the value of the pin from the command line. If you’re not already running commands as root, type sudo su.

7. As with the previous example, you need to export the input pin to userspace:

   # echo 24 > /sys/class/gpio/export
   

8. Let’s change to the directory that was created during the export operation:

   # cd /sys/class/gpio/gpio24
   

9. Now set the direction of the pin to input:

   # echo in > direction
   

Figure 6-7. Connecting a button to the Raspberry Pi

10. To read the value of the of the pin, you’ll use the cat command, which will print the contents of files to the terminal. The command cat gets its name because it can also be used to concatenate, or join, files. It can also display the contents of a file for you:

    # cat value
    0
    

11. The zero indicates that the pin is connected to ground. Now press and hold the button while you execute the command again:

    # cat value
    1
    

12. If you see the number 1, you’ll know you’ve got it right!

    Tip

    To easily execute a command that you’ve previously executed, hit the up arrow key until you see the command that you want to run and then hit Enter.

Now that you can use the Linux command line to control an LED or read the status of a button, let’s use a few of Linux’s built-in tools to create a very simple project that uses digital input and output.

Scripting Commands

A shell script is a file that contains a series of commands (just like the ones you’ve been using to control and read the pins). Take a look at the following shell script and the explanation of the key lines:

#!/bin/bash 
echo Exporting pin $1. 
echo $1 > /sys/class/gpio/export 
echo Setting direction to out.
echo out > /sys/class/gpio/gpio$1/direction 
echo Setting pin high.
echo 1 > /sys/class/gpio/gpio$1/value

This line is required for all shell scripts.

$1 refers to the first command-line argument.

Instead of exporting a specific pin number, the script uses the first command-line argument.

Notice that the first command-line argument replaces the pin number here as well.

Save that as a text file called on.sh and make it executable with the chmod command:

root@raspberrypi:/home/pi# chmod +x on.sh

A command-line argument is a way of passing information into a program or script by typing it in after name of the command. When you’re writing a shell script, $1 refers to the first command-line argument, $2 refers to the second, and so on. In the case of on.sh, you’ll type in the pin number that you want to export and turn on. Instead of hard coding pin 25 into the shell script, it’s more universal by referring to the pin that was typed in at the command line. To export pin 25 and turn it on, you can now type:

root@raspberrypi:/home/pi/# ./on.sh 25 
Exporting pin 25.
Setting direction to out.
Setting pin high.

The ./ before the filename indicates that you’re executing the script in the directory you’re in.

If you still have the LED connected to pin 25 from earlier in the chapter, it should turn on. Let’s make another shell script called off.sh, which will turn the LED off. It will look like this:

#!/bin/bash
echo Setting pin low.
echo 0 > /sys/class/gpio/gpio$1/value
echo Unexporting pin $1
echo $1 > /sys/class/gpio/unexport

Now let’s make it executable and run the script:

root@raspberrypi:/home/pi/temp# chmod +x off.sh
root@raspberrypi:/home/pi/temp# ./off.sh 25
Setting pin low.
Unexporting pin 25

If everything worked, the LED should have turned off.

Connecting a Lamp

Of course, a tiny little LED isn’t going to give off enough light to fool burglars into thinking that you’re home, so let’s hook up a lamp to the Raspberry Pi:

1. Remove the LED connected to pin 25.

2. Connect two strands of hookup wire to the breadboard, one that connects to pin 25 of the Raspberry Pi and the other to the ground bus.

3. The strand of wire that connects to pin 25 should be connected to the “+in” terminal of the PowerSwitch Tail.

4. The strand of wire that connects to ground should be connected to the “-in” terminal of the PowerSwitch Tail. Compare your circuit to Figure 6-8.

5. Plug the PowerSwitch Tail into the wall and plug a lamp into the PowerSwitch Tail. Be sure the lamp’s switch is in the on position.

6. Now when you execute ./on.sh 25, the lamp should turn on; and if you execute ./off.sh 25, the lamp should turn off!

Figure 6-8. Connecting a PowerSwitch Tail II to the Raspberry Pi

Scheduling Commands with cron

So now you’ve packaged up a few different commands into two simple commands that can turn a pin on or off. And with the lamp connected to the Raspberry Pi through the PowerSwitch Tail, you can turn the lamp on or off with a single command. Now you can use cron to schedule the light to turn on and off at different times of day. cron is Linux’s job scheduler. With it, you can set commands to execute on specific times and dates, or you can have jobs run on a particular period (for example, once an hour). You’re going to schedule two jobs: one of them will turn the light on at 8:00 p.m., and the other will turn the light off at 2:00 a.m.

To add these jobs, you’ll have to edit the cron table (a list of commands that Linux executes at specified times):

root@raspberrypi:/home/pi/# crontab -e

This will launch a text editor to change root’s cron table (to change to the root user, type sudo su). At the top of the file, you’ll see some information about how to modify the cron table. Use your arrow keys to get to the bottom of the file and add these two entries at the end of the file:

0 20 * * * /home/pi/on.sh 25
0 2 * * * /home/pi/off.sh 25

Press Ctrl-X to exit, press y to save the file when it prompts you, and hit Enter to accept the default filename. When the file is saved and you’re back at the command line, it should say installing new crontab to indicate that the changes you’ve made are going to be executed by cron.