Pin Numbering

As I mentioned, there are two numbering schemas for the 40-pin header: board and BCM.

Board numbering simply numbers the pins sequentially. Pin 1 is the one closest to the micro SD card, and pin 2 is the adjacent pin closest to the outer edge of the Pi. The numbering continues this way, with odd-numbered pins on the inside row and even-numbered pins on the outside. Pin 40 is the pin on the edge of the board, near the USB ports.

BCM numbering is not nearly as straightforward. BCM stands for Broadcom, the manufacturer of the SoC (system on a chip) that drives the Pi. On the Raspberry Pi 2, the processor is the BCM2836; on the Raspberry Pi 3, it’s the BCM2837. BCM numbering refers to the pin numbers of the Broadcom chip, which can vary between versions. The BCM2836 and BCM2837 have the same pin-out, so there is no difference between the Pi 2 and Pi 3.

To make connecting electronic components to the 40-pin header, we will use the Adafruit T-Cobbler Plus and a breadboard. The T-Cobbler has pin information stenciled on the board for quick reference; however, the T-Cobbler uses BCM numbering. Thus, we will use BCM numbering.

Connecting to the Raspberry Pi

There are several ways to connect the pins from the header to other devices. The motor controller that we will use is an example of a board that sits directly on top of the header. In Raspberry Pi terminology, these boards are referred to as hats or plates .

Another option is to directly connect to the pins using jumpers. For many people, this is the preferred method during prototyping.

I prefer a third method, which is to use another board from Adafruit called the Pi Cobbler. There are a few versions of the cobbler, but I prefer the Adafruit T-Cobbler Plus for Raspberry Pi (see Figure 4-2). This board is designed to attach to a breadboard via a ribbon cable. It uses a 40-pin header configured perpendicular to the pins that plug into the breadboard. This moves the ribbon cable attachment off the breadboard and allows better access to the holes.

One advantage of using the cobbler is that the pin breakouts are clearly marked. When we start building our circuits, it will be very easy to see exactly what you are hooking up. This also makes it easier to identify which pins are being used for your code. When you declare pin 21 as an output pin, you will know exactly which pin it is on the board.

Limitations of Raspberry Pi’s GPIO

There are a few things to keep in mind as you are working with GPIO.

First, the Raspberry Pi that we set up is not a real-time device. Debian Linux is a full operating system with many layers of abstraction from the hardware. This means that commands to the hardware are not direct. Rather, the commands are passed through several operations before and after the CPU sends them to the board. Python operates in another abstraction layer. Each of these layers introduces a certain degree of lag. It’s generally not perceivable to us, but it can make a huge difference in robot operations. There are distributions of Debian that are more real time, designed for industrial applications, but the standard Raspbian version that we are using is not one of these.

Second, there is no analog input on the Pi. Well, there is one, but it is shared with the serial port, which we will likely use later for something else. So, it’s better to accept that there are no analog input pins. You will see why this is important in Chapter 5.

Third, the Pi only has two PWM capable pins. PWM stands for pulse width modulation , which is how we send a varied signal to an external device. This means that there are only two pins on the header that can simulate an analog output. Both of these pins are also shared with the audio output of the Pi, which is not optimal.

The good news is there’s a simple solution for all of these issues, which is simply to introduce an external microcontroller that is in real time, offers multiple analog inputs, and provides more than two PWM outputs. We will use this with the Arduino in Chapter 5. The Arduino is basically a prototyping board for the AVR AT series of microcontrollers. These chips are directly connected to the hardware and do not have the layers of abstraction that you find in most SoC processors, like those on the Pi. There are other advantages to using an Arduino, which I discuss in Chapter 5.

Accessing GPIO with Python

Hardware is only part of the equation. We’ll use our new Python skills to program the behavior we want. In order to do that, we’ll use the RPi.GPIO library. You will recall from Chapter 3 that a library is a collection of classes and functions that provide additional functionality.

In robotics, a new piece of hardware, sensor, or other component frequently has a library to allow you to use it more easily. Sometimes the library is generic, such as RPi.GPIO; other times, the library is made for a specific device. For example, we will use a library specific to the motor controller board in Chapter 7. As you add more hardware to your robot, you frequently have to download the new libraries from the manufacturer’s website. You will see this in action when we start working with the motor controller.

The GPIO library provides objects and functions to access the GPIO pins. Raspbian comes with the library installed, so it should be ready to go. For more information on how to use the package, visit https://sourceforge.net/p/raspberry-gpio-python/wiki/BasicUsage/ .

To use the GPIO library, we need to do two things: import the package and then tell it which mode we’ll use to access the pins. As I discussed earlier, there are two modes—board and BCM—that essentially tell the system which numbering reference to use.

Board mode references the numbering on the P1 header of the Raspberry Pi. Since this numbering remains constant, for backward compatibility, you won’t need to change your pin numbering in your code, based on the board revision.

In contrast, BCM mode refers to the pin numbering from the Broadcom SoC, which means that on newer versions of the Pi, it is possible for the pin layout to change. Fortunately, this pin layout has not changed between the BCM2836 used in the Pi 2, and the BCM2837 used in the Pi3.

For our purposes, we’ll use BCM mode—simply because that is what is illustrated on the T-Cobbler.

Every program using the GPIO header includes the following two lines of code:

Simple Output: LED Example

The simplest example is the ubiquitous hardware version of “Hello World”—the blinking LED. Our first GPIO project is to connect an LED to the Pi and to use a Python script to make the LED blink. Let’s start by hooking up the circuit. To do this, you need a breadboard, the T-Cobbler, an LED, a 220ohm (Ω) resistor, and two short pieces of wire to use as jumpers.

Simple Input

Now that we’ve seen how easy it is to send out a signal, it’s time to get some information back into the Pi. We’ll do this through two examples. First, the push-button; in this example, the Pi is set up to take input from a simple push-button and indicate in the terminal when the button has been pushed. The second example uses a sonic rangefinder to read the distance to an object. The output will be displayed in the terminal.

Sonic Rangefinder Example

For this example, let’s use the HC-SR04 ultrasonic sensor to determine the distance to an object. You’ll put the call into a loop that allows us to get constant distance readings. You’ll use the libraries used in the previous example to access the GPIO pins.

This exercise introduces you to one of the key factors to watch out for with the Pi and many other devices: voltage difference between the sensors and the pins. Many sensors are designed to work at 5 volts. The Pi, however, uses 3.3 volts in its logic. That means all of the I/O pins are designed to work with 3.3 volts. Applying a 5V signal to any of these pins can cause severe damage to your Pi. The Pi does provide a few 5V source pins, but we need to reduce the returning signal to 3.3 volts.

Hooking Up the Circuit

This time, the circuit is a bit more complicated. Really. Keep in mind that the sensor works on 5 volts. The Pi’s GPIO pins work on 3.3 volts. Feeding a 5V return signal into a 3.3V pin can damage the Pi. To keep that from happening, let’s add a simple voltage divider to the echo pin.

Let’s do some math.

We have 5 volts in and want 3.3 volts out, and we are using a 1kΩ resistor as part of the circuit. So…

The following is the parts list:

• HC-SR04

• 1kΩ resistor

• 2kΩ resistor

  You can use two 1kΩ resistors in series, or a more popular, similar resistor is the 2.2kΩ. That’s what we’ll use.

• 4 male-to-female jumpers

• 4 male-to-male jumpers

Here’s the setup.

1. 1.
   Attach the T-Cobbler, as shown in Figure 4-6. One row of pins should be on either side of the split in the board. The placement is up to you; however, I generally attach it so that the ribbon cable header is off the board. This allows maximum access to the breadboard.

   

    
2. 2.

   Make sure that the ground jumper is secure between the ground pin and the ground rail.

    
3. 3.

   Add a jumper between one of the 5V pins and the power rail.

    
4. 4.

   Use a male-to-female jumper to connect the ground pin on the SR04 to the ground rail.

    
5. 5.

   Connect the VCC or 5V pin from the SR04 to the power rail.

    
6. 6.

   Connect the trig pin on the SR04 to pin 20 of the T-Cobbler.

    
7. 7.

   Connect the 2kΩ resistor from an empty 5-pin rail to the ground rail.

    
8. 8.

   Connect the 1kΩ resistor from the rail connected to the 2kΩ resistor to another empty 5-pin rail.

    
9. 9.

   Connect another jumper between the rail connected to the 2kΩ resistor and pin 21 on the T-Cobbler.

    
10. 10.

    Connect the SR04 echo pin to the rail that the other end of the 1kΩ resistor is connected to.

     

That completes the wiring. Now let’s get the code set up.

Writing the Code

The HC-SR04 ultrasonic rangefinder works by measuring the time it takes for an ultrasonic pulse to return to the sensor. We’ll send out a 10-microsecond pulse and then listen for the pulse to return. By measuring the length of the returned pulse, we can use a little math to calculate the distance in centimeters.

Distance is calculated as speed × time. It’s derived from the formula speed = distance ÷ time. At sea level, sound travels at a rate of 343m per second, or 34,300cm per second. Since we are actually measuring the time it takes for the pulse to reach its target and return, we really only need half of that value. Let’s working with the following formula:

Distance = 17,150 × time

The code simply sends out a 10μS pulse, measures the time it takes to return, calculates the estimated distance in centimeters, and displays it in the terminal window.

Create a new Python 3 file.

If using IDLE, do the following:

1. 1.

   Open IDLE for Python 3.

    
2. 2.

   Click New.

    
3. 3.

   Save the file as gpio_sr04.py in your project folder.

    

If using a terminal window, do the following:

1. 1.

   Navigate to your project folder. On my Pi it is

   $ cd ~/TRG-RasPi-Robot/code

    
2. 2.

   Type touch gpio_sr04.py.

    
3. 3.

   Type idle3 gpio_sr04.py. This opens the empty file in the IDLE IDE for Python 3.

    
4. 4.

   Enter the following code:

   # GPIO example using an NC-SR04 ultrasonic rangefinder

   # import the GPIO and time libraries

   import RPi.GPIO as GPIO

   import time

   # Set the GPIO mode to BCM mode and disable warnings

   GPIO.setmode(GPIO.BCM)

   GPIO.setwarnings(False)

   # Define pins

   trig = 20

   echo = 21

   GPIO.setup(trig,GPIO.OUT)

   GPIO.setup(echo,GPIO.IN)

   print("Measuring distance")

   # Begin while loop

   while True:

       # Set trigger pin low got 1/10 second

       GPIO.output(trig,False)

       time.sleep(0.1)

       # Send a 10uS pulse

       GPIO.output(trig,True)

       time.sleep(0.00001)

       GPIO.output(trig,False)

       # Get the start and end times of the return pulse

       while GPIO.input(echo)==0:

           pulse_start = time.time()

       while GPIO.input(echo)==1:

           pulse_end = time.time()

       pulse_duration = pulse_end - pulse_start

       # Calculate the distance in centimeters

       distance = pulse_duration * 17150

       distance = round(distance, 2)

       # Display the results. end = ' ' forces the output to the same line

       print("Distance: " + str(distance) + "cm      ", end = ' ')
    
5. 5.

   Open a new terminal window and navigate to your project folder.

    
6. 6.

   Type chmod +x gpio_sr04.py.

    
7. 7.

   To run the code, type

   sudo python3 gpio_sr04.py