Sparkfun Raspberry gPIo User manual

Raspberry gPIo





Introduction

Relative to its size the Raspberry Pi is a powerhorse of a computer – it can

drive HDMI displays, process mouse, keyboard, and camera inputs,

connect to the Internet, and run full-featured Linux distributions. But it’s

more than just a small computer, it’s a hardware prototyping tool! The Pi

has bi-directional I/O pins, which you can use to drive LEDs, spin motors,

or read button presses.

This tutorial applies to the Raspberry Pi Model B, the Raspberry Pi Model

B+ and the new Raspberry Pi 2 Model B.

Example Pi Wedge on a model B

Driving the Raspberry Pi’s I/O lines requires a bit of programming.

Programming in what language? Take your pick! A quick glance at the

Raspberry Pi GPIO examples shows that there are dozens of

programming-language-choices. We’ve pared that list down, and ended up

with two really solid, easy tools for driving I/O: Python and C (using the

WiringPi library).

If you’ve never driven an LED or read in a button press using the Raspberry

Pi, this tutorial should help to get you started. Whether you’re a fan of the

easily-readable, interpretive scripting language Python or more of a die-

hard C programmer, you’ll find a programming option that suits our needs.

Covered In This Tutorial

In this tutorial we’ll show two different approaches to reading and driving

the Raspberry Pi’s GPIO pins: python and C. Here’s a quick overview of

what’s covered:

• GPIO Pinout – An overview of the Pi’s GPIO header.

•Python API and Examples

Page 1 of 1

Raspberry gPIo SparkFun Wish List

◦RPi.GPIO API – An overview of the Python functions you can

use to drive GPIO.

◦RPi.GPIO Example – An example Python script that shows off

both input and output functionality.

•C (and WiringPi) API and Examples

◦WiringPi Setup and Test – How to install WiringPi and then

take it for a test drive on the command line.

◦WiringPi API – An overview of the basic functions provided by

the WiringPi library.

◦WiringPi Example – A simple example program that shows off

WiringPi’s input and output capabilities.

• Using an IDE – How to download and install Geany. Our favorite IDE

for programming on the Raspberry Pi.

Each programming language has it’s share of pros and cons. Python is

easy (especially if your a programming novice) and doesn’t require any

compilation. C is faster and may be easier for those familiar with the old

standby.

What You’ll Need

Here’s a wishlist-full of everything we used for this tutorial.

Raspberry Pi - Model B

DEV-11546

Who wants pi? The Raspberry Pi has made quite a splash since it wa…

SparkFun Pi Wedge

KIT-12652

This is the SparkFun Pi Wedge, a small board that connects to the Ra…

(2) Breadboard - Self-Adhesive (White)

PRT-12002

This is your tried and true white solderless breadboard. It has 2 power…

Jumper Wires Standard 7" M/M Pack of 30

PRT-11026

If you need to knock up a quick prototype there's nothing like having a…

Momentary Pushbutton Switch - 12mm Square

COM-09190

This is a standard 12mm square momentary button. What we really li…

Resistor 330 Ohm 1/6 Watt PTH - 20 pack

COM-11507

1/6 Watt, +/- 5% tolerance PTH resistors. Commonly used in breadbo…

LED - Basic Red 5mm

COM-09590

LEDs - those blinky things. A must have for power indication, pin stat…

Some further notes on that bill of materials:

• Your Raspberry Pi should have an SD card with Raspbian installed

on it. Check out our How to Install Raspbian tutorial for help with that.

• We’re also assuming you have the necessary mouse, keyboard and

display hooked up to your Pi.

• Your Pi will need an Internet connection to download WiringPi. You

can use either Ethernet or WiFi (check out our Raspberry Pi WiFi

tutorial for help with that.

• The Pi Wedge isn’t quite required, but it does make life a lot easier. If

you want to skip the breakout, you can instead use Male-to-Female

jumpers to connect from Pi to breadboard.

• Of course, feel free to swap in your preferred button and LEDs.

Page 2 of 1

Suggested Readin

This tutorial will assume you have Raspbian installed on your Raspberry

Pi. Raspbian is the most popular, well-supported Linux distribution available

for the Pi. If you don’t have Raspbian set up, check out our Setting Up

Raspbian tutorial before continuing down this rabbit hole.

Other, more general purpose tutorials you might be interested in reading

include:

• Pulse-Width Modulation – You can use PWM to dim LEDs or send

signals to servo motors. The RPi has a single PWM-capable pin.

• Light-Emitting Diodes (LEDs) – To test the output capabilities of the

Pi, we’ll be driving a lot of LEDs.

• Switch Basics – And to test inputs to the Pi, we’ll be using buttons

and switches.

• Pull-Up Resistors – The Pi has internal pull-up (and pull-down)

resistors. These are very handy when you’re interfacing buttons with

the little computer.

Suggested Viewing

Check out our Raspberry Pi video tutorials if you want a more visual

introduction to the Pi!

• Getting Started With The Raspberry Pi

◦Part 1

◦Part 2

◦Part 3

GPIO Pinout

The Raspberry Pi offers up its GPIO over a standard male header on the

board. Over the years the header has expanded from 26 pins to 40 pins

while maintaining the original pinout.

Header configuration for early and late model Pi computers

If you’re coming to the Raspberry Pi as an Arduino user, you’re probably

used to referencing pins with a single, unique number. Programming the

Pi’s hardware works much the same, each pin has its own number…and

then some.

There are (at least) two, different numbering schemes you may encounter

when referencing Pi pin numbers: (1) Broadcom chip-specific pin numbers

and (2) P1 physical pin numbers. You’re usually free to use either number-

system, but many programs require that you declare which scheme you’re

using at the very beginning of your program.

Here’s a table showing all 26 pins on the P1 header, including any special

function they may have, and their dual numbers:

Page 3 of 1

Element14 pin description, annotated

Wedge

Silk

Python

(BCM)

WiringPi

GPIO Name P1 Pin

Number Name WiringPi

GPIO

Python

(BCM)

Wedge

Silk

3.3v DC

Power 125v DC Power

SDA 8 GPIO02

(SDA1, I2C) 345v DC Power

SCL 9 GPIO03

(SCL1, I2C) 56 Ground

G4 4 7 GPIO04

(GPIO_GCLK) 78 GPIO14

(TXD0) 15 TXO

Ground 910 GPIO15

(RXD0) 16 RXI

G17 17 0 GPIO17

(GPIO_GEN0) 11 12 GPIO18

(GPIO_GEN1) 118G18

G27 27 2 GPIO27

(GPIO_GEN2) 13 14 Ground

G22 22 3 GPIO22

(GPIO_GEN3) 15 16 GPIO23

(GPIO_GEN4) 423G23

3.3v DC

Power 17 18 GPIO24

(GPIO_GEN5) 524G24

MOSI 12 GPIO10

(SPI_MOSI) 19 20 Ground

MISO 13 GPIO09

(SPI_MISO) 21 22 GPIO25

(GPIO_GEN6) 625G25

(no

worky

14)

GPIO11

(SPI_CLK) 23 24 GPIO08

(SPI_CE0_N) 10 CD0

Ground 25 26 GPIO07

(SPI_CE1_N) 11 CE1

IDSD 30 ID_SD (I2C ID

EEPROM) 27 28 ID_SC (I2C ID

EEPROM) 31 IDSC

G05 5 21 GPIO05 29 30 Ground

G6 6 22 GPIO06 31 32 GPIO12 26 12 G12

G13 13 23 GPIO13 33 34 Ground

G19 19 24 GPIO19 35 36 GPIO16 27 16 G16

G26 26 25 GPIO26 37 38 GPIO20 28 20 G20

Ground 39 40 GPIO21 29 21 G21

This table shows the Pi pin header numbers, element14 given names,

wiringPi numbers, Python numbers, and related silkscreen on the wedge.

Page 4 of 1

Note: The Broadcom pin numbers above relate to Pi Model 2 and later

only. If you have an older Rev1 Pi, check out this link for your Broadcom pin

numbers.

As you can see, the Pi not only gives you access to the bi-directional I/O

pins, but also Serial (UART), I C, SPI, and even some PWM (“analog

output”).

Hardware Setup

To get a head start you can assemble the circuit now. We’ll use this setup

for both the C and Python examples. We’ll use two LEDs to test the output

functionality (digital and PWM), and a button to test the input.

connections to original pi

connections to the pi B + and pi 2 B

Page 5 of 1

Our two LEDs are connected to the Pi’s GPIO 18 and GPIO 23 – those

are the Broadcom chip-specific numbers. If you’re basing your wiring off the

P1 connector pin numbers, that’d be pins 12 and 16.

The button is connected to Broadcom GPIO 17, aka P1 pin 11.

If you have Pi Wedge, the hookup should be pretty straight-forward. It’ll look

a little something like this when you’re done:

If you don’t have a Pi Wedge, male-to-female jumper wires help to make an

easy transition from Pi to breadboard.

Python (RPi.GPIO) API

We’ll use the RPi.GPIO module as the driving force behind our Python

examples. This set of Python files and source is included with Raspbian,

so assuming you’re running that most popular Linux distribution, you don’t

need to download anything to get started.

On this page we’ll provide an overview of the basic function calls you can

make using this module.

Setup Stuff

In order to us RPi.GPIO throughout the rest of your Python script, you need

to put this statement at the top of your file:

import RPi.GPIOas GPIO

That statement “includes” the RPi.GPIO module, and goes a step further by

providing a local name – GPIO – which we’ll call to reference the module

from here on.

Pin Numbering Declaration

After you’ve included the RPi.GPIO module, the next step is to determine

which of the two pin-numbering schemes you want to use:

1. GPIO.BOARD – Board numbering scheme. The pin numbers follow the

pin numbers on header P1.

2. GPIO.BCM – Broadcom chip-specific pin numbers. These pin

numbers follow the lower-level numbering system defined by the

Raspberry Pi’s Broadcom-chip brain.

If you’re using the Pi Wedge, we recommend using the GPIO.BCM definition

– those are the numbers silkscreened on the PCB. The GPIO.BOARD may

be easier if you’re wiring directly to the header.

To specify in your code which number-system is being used, use the

Page 6 of 1

GPIO.setmode() function. For example…

GPIO.setmode(GPIO.BCM)

…will activate the Broadcom-chip specific pin numbers.

Both the import and setmode lines of code are required, if you want to

use Python.

Setting a Pin Mode

If you’ve used Arduino, you’re probably familiar with the fact that you have

to declare a “pin mode” before you can use it as either an input or output.

To set a pin mode, use the setup([pin],[GPIO.IN,GPIO.OUT] function.

So, if you want to set pin 18 as an output, for example, write:

GPIO.setup(18,GPIO.OUT)

Remember that the pin number will change if you’re using the board

numbering system (instead of 18, it’d be 12).

Outputs

Digital Output

To write a pin high or low, use the

GPIO.output([pin],[GPIO.LOW,GPIO.HIGH]) function. For example, if

you want to set pin 18 high, write:

GPIO.output(18,GPIO.HIGH)

Writing a pin to GPIO.HIGH will drive it to 3.3V, and GPIO.LOW will set it to

0V. For the lazy, alternative to GPIO.HIGH and GPIO.LOW , you can use

either 1, True , 0or False to set a pin value.

PWM (“Analog”) Output

PWM on the Raspberry Pi is about as limited as can be – one, single pin is

capable of it: 18 (i.e. board pin 12).

To initialize PWM, use GPIO.PWM([pin],[frequency]) function. To make

the rest of your script-writing easier you can assign that instance to a

variable. Then use pwm.start([dutycycle]) function to set an initial

value. For example…

pwm= GPIO.PWM(18,1000)

pwm.start(50)

…will set our PWM pin up with a frequency of 1kHz, and set that output to a

50% duty cycle.

To adjust the value of the PWM output, use the

pwm.ChangeDutyCycle([dutycycle]) function. [dutycycle] can be any

value between 0 (i.e 0%/LOW) and 100 (ie.e 100%/HIGH). So to set a pin

to 75% on, for example, you could write:

pwm.ChangeDutyCycle(75)

To turn PWM on that pin off, use the pwm.stop() command.

Simple enough! Just don’t forget to set the pin as an output before you use

it for PWM.

Inputs

Page 7 of 1

If a pin is configured as an input, you can use the GPIO.input([pin])

function to read its value. The input() function will return either a True or

False indicating whether the pin is HIGH or LOW. You can use an if

statement to test this, for example…

if GPIO.input(17):

print("Pin11isHIGH")

else:

print("Pin11isLOW")

…will read pin 17 and print whether it’s being read as HIGH or LOW.

Pull-Up/Down Resistors

Remember back to the GPIO.setup() function where we declared whether

a pin was an input or output? There’s an optional third parameter to that

function, which you can use to set pull-up or pull-down resistors. To use a

pull-up resistor on a pin, add pull_up_down=GPIO.PUD_UP as a third

parameter in GPIO.setup . Or, if you need a pull-down resistor, instead use

pull_up_down=GPIO.PUD_DOWN .

For example, to use a pull-up resistor on GPIO 17, write this into your

setup:

GPIO.setup(17,GPIO.IN,pull_up_down=GPIO.PUD_UP)

If nothing is declared in that third value, both pull-resistors will be disabled.

Etc.

Delays

If you need to slow your Python script down, you can add delays. To

incorporate delays into your script, you’ll need to include another module:

time . This line, at the top of your script, will do it for you:

includetime

Then, throughout the rest of your script, you can use

time.sleep([seconds]) to give your script a rest. You can use decimals to

precisely set your delay. For example, to delay 250 milliseconds, write:

time.sleep(0.25)

The time module includes all sorts of useful functions, on top of sleep .

Check out the reference here.

Garbage Collecting

Once your script has run its course, be kind to the next process that might

use your GPIOs by cleaning up after yourself. Use the GPIO.cleanup()

command at the end of your script to release any resources your script may

be using.

Your Pi will survive if you forget to add this command, but it is good practice

to include wherever you can.

Now then. Lets incorporate everything we learned here into an example

script to try everything out.

Python (RPi.GPIO) Example

Follow along as we use the basic RPi.GPIO functions from the last page to

create a simple example GPIO script.

Page 8 of 1

1. Create a Fil

To begin, we need to create a Python file. You can do this through the GUI-

based file explorer. Or, if you want a terminal-based solution, open up

LXTerminal, and navigate to a folder you’d like the file to live (or create

one). And create a new folder with these commands:

pi@raspberrypi ~/code $ mkdir python

pi@raspberrypi ~/code $ cd python

Create a file – we’ll call ours “blinker” – and terminate it with a .py

extension. Then open it up in your favorite text editor. Nano works, as does

Pi’s default GUI text editor, Leafpad.

pi@raspberrypi ~/code/python $ touch blinker.py

pi@raspberrypi ~/code/python $ leafpad blinker.py &

That’ll open up a blank text file (the “&” will open it in the background,

leaving the terminal in place for future use). Time for some code!

2. Codify

Here’s an example sketch that incorporates everything we learned on the

last page. It does a little input and output, and even handles some PWM.

This assumes you’ve set up the circuit as arranged on the Hardware Setup

page.

Page 9 of 1

#Externalmoduleimports

import RPi.GPIOas GPIO

import time

#PinDefinitons:

pwmPin=18#Broadcompin18(P1pin12)

ledPin=23#Broadcompin23(P1pin16)

butPin=17#Broadcompin17(P1pin11)

dc=95#dutycycle(0100)forPWMpin

#PinSetup:

GPIO.setmode(GPIO.BCM)#Broadcompinnumberingscheme

GPIO.setup(ledPin,GPIO.OUT)#LEDpinsetasoutput

GPIO.setup(pwmPin,GPIO.OUT)#PWMpinsetasoutput

pwm= GPIO.PWM(pwmPin,50)#InitializePWMonpwmPin100Hzf

requency

GPIO.setup(butPin,GPIO.IN,pull_up_down=GPIO.PUD_UP)#Butto

npinsetasinputw/pullup

#InitialstateforLEDs:

GPIO.output(ledPin,GPIO.LOW)

pwm.start(dc)

print("Herewego!PressCTRL+Ctoexit")

try:

while 1:

if GPIO.input(butPin):#buttonisreleased

pwm.ChangeDutyCycle(dc)

GPIO.output(ledPin,GPIO.LOW)

else:#buttonispressed:

pwm.ChangeDutyCycle(100dc)

GPIO.output(ledPin,GPIO.HIGH)

time.sleep(0.075)

GPIO.output(ledPin,GPIO.LOW)

time.sleep(0.075)

except KeyboardInterrupt:#IfCTRL+Cispressed,exitcleanl

pwm.stop()#stopPWM

GPIO.cleanup()#cleanupallGPIO

After you’ve typed all of that in (don’t forget your whitespace!) save.

Running the Script

The RPi.GPIO module requires administrator privileges, so you’ll need to

tag a sudo on to the front of your Python script call. To run your

“blinker.py” script, type:

pi@raspberrypi ~/code/python $ sudo python blinker.py

With the code running, press the button to turn on the digital LED. The

PWM-ing LED will invert its brightness when you press the button as well.

Press CTRL+C to cleanly exit the script.

C (WiringPi) Setup

Page 10 of 1

Table of contents

Other sparkfun Motherboard manuals

sparkfun

sparkfun nRF52832 Technical document

sparkfun

sparkfun MAG3110 Technical document

sparkfun

sparkfun Qwiic 12-Bit ADC Technical document

sparkfun

sparkfun Pi Servo Hat Technical document

sparkfun

sparkfun Pro Micro Technical document

sparkfun

sparkfun ProtoShield User manual

sparkfun

sparkfun BeagleBone Black Proto Cape Technical document

sparkfun

sparkfun Qwiic Shield for Teensy Technical document

sparkfun

sparkfun ZOE-M8Q User manual

sparkfun

sparkfun MPR121 Technical document

sparkfun

sparkfun gator:bit v2 Technical document

sparkfun

sparkfun DEV-16138 Technical document

sparkfun

sparkfun Qwiic SHIM for Raspberry Pi Technical document

sparkfun

sparkfun gator:particle Technical document

sparkfun

sparkfun Qwiic MP3 Trigger Technical document

sparkfun

sparkfun XBee Shield Technical document

sparkfun

sparkfun PRT-13144 Technical document

sparkfun

sparkfun RV-8803 Technical document

sparkfun

sparkfun KIT-14173 Technical document

sparkfun

sparkfun Qwiic Shield for Thing Plus Technical document

sparkfun

sparkfun DEV-14044 Technical document

sparkfun

sparkfun ESP8266 Technical document

sparkfun

sparkfun Power Delivery Board - USB-C (Qwiic) Technical document

sparkfun

sparkfun Simon Says User manual

Popular Motherboard manuals by other brands

DFI

DFI SD170 user manual

ASROCK

ASROCK ROMED8-2T user manual

Asus

Asus P2L97A user manual

Winmate

Winmate IC70 user manual

Asus

Asus MES-B user manual

Grantech

Grantech SYS8F377VGGA-3OMN user manual

Telit Wireless Solutions

Telit Wireless Solutions SL869-3DR user guide

Gigabyte

Gigabyte GA-9IVDT user manual

Texas Instruments

Texas Instruments ADS8372EVM user guide

Commell

Commell MS-C73 user manual

IBT Technologies

IBT Technologies MB860 user manual

Nvidia

Nvidia TEGRA DG-04927-001_V01 user guide

Biostar

Biostar M7VIT Bravo Description

Intel

Intel D33217CK specification

Asus

Asus F1A55-M LX PLUS R2.0 user manual

EPC

EPC EPC9147C quick start guide

Asus

Asus EX-B760M-V5 D4 quick start guide

EPOX

EPOX MU-8KHA0010 user manual

sparkfun Raspberry gPIo User manual

Popular Motherboard manuals by other brands