Raspberry gPIo
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:
language:Python
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:
GPIO.BOARD
-- Board numbering scheme. The pin numbers follow the pin numbers on header P1.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 GPIO.setmode()
function. For example...
language:Python
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:
language:Python
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:
language:Python
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
, 0
or 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...
language:Python
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:
language:Python
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
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...
language:Python
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:
language:Python
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:
language:Python
import 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:
language:Python
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.