Chapter 1: Basics of RPi.GPIO Module

Importing the Module

To import the RPi.GPIO module:

import RPi.GPIO as GPIO

By doing this, you can refer to it as GPIO for the rest of this script. You can check if the module was imported successfully by throwing an exception:

try:
 import RPi.GPIO as GPIO
except RuntimeError:
 print("Error importing RPi.GPIO! This is probably because you need superuser privileges. You can achieve this by using 'sudo' to run your script")

Pin Numbering

In RPi.GPIO, there are two methods to number the IO pins on the Raspberry Pi. The first is to use the BOARD numbering system. This refers to the pin numbers on the P1 header of the Raspberry Pi board. The advantage of using this numbering system is that your hardware will always work regardless of the version of the RPi board. You do not need to reconnect connectors or change code. The second numbering system is BCM numbering. This is a lower-level way of working – it refers to the channel numbers on the Broadcom SOC. You must always refer to which channel number points to which pin on the Raspberry Pi board using a chart. Your script may break between revisions of the Raspberry Pi board.

GPIO.setmode(GPIO.BOARD)
 # or
GPIO.setmode(GPIO.BCM)

To detect which pin numbering system is set (for example, when multiple Python modules use GPIO):

mode = GPIO.getmode()

The value of the mode is 10 (GPIO.BOARD), 11 (GPIO.BCM), or empty (not set).

Warning

You may have multiple scripts/circuits on the GPIO of the Raspberry Pi. Therefore, if RPi.GPIO detects that a pin has been configured to something other than the default (input), you will receive a warning when attempting to configure it again. To disable these warnings:

GPIO.setwarnings(False)

Configuring a Channel (Pin)

You need to set each channel you are using to either input or output. To configure a channel as input:

GPIO.setup(channel, GPIO.IN)

(where channel is the channel number based on the numbering system you specified (BOARD or BCM)). For more advanced information on setting up input channels, see here. To set a channel as output:

GPIO.setup(channel, GPIO.OUT)

(where channel is the channel number based on the numbering system you specified (BOARD or BCM)). You can also specify an initial value for the output channel:

GPIO.setup(channel, GPIO.OUT, initial=GPIO.HIGH)

Setting Multiple Channels with One Command

You can set multiple channels with each call (starting from 0.5.8). For example:

chan_list = [11,12] # Set a list and add any number of channels!
 # You can also change the list to a tuple, i.e.:
 # chan_list = (11,12)
GPIO.setup(chan_list, GPIO.OUT)

Input

To read the value of a GPIO pin:

GPIO.input(channel)

(where channel is the channel number based on the numbering system you specified (BOARD or BCM)). This will return 0 / GPIO.LOW / False or 1 / GPIO.HIGH / True.

Output

To set the GPIO pin to output state:

GPIO.output(channel, state)

(where channel is the channel number based on the numbering system you specified (BOARD or BCM)). The state can be 0 / GPIO.LOW / False or 1 / GPIO.HIGH / True.

Output to Multiple Channels

You can set output for multiple channels in the same command (starting from 0.5.8). For example:

chan_list = [11,12] # You can also change the list to a tuple
GPIO.output(chan_list, GPIO.LOW) # Set all channels to GPIO.LOW
GPIO.output(chan_list, (GPIO.HIGH, GPIO.LOW)) # Set the first channel to high, the second to low

Cleaning Up Configured Pin States

At the end of any script, it is best to clean up any resources you may have used. This is no different in the use of RPi.GPIO. Returning all used channels to inputs without pull-ups/down can prevent accidental damage to the RPi. Note that this will only clean up GPIO channels used by the script. Note that GPIO.cleanup() will also clear the numbering system in use. Clean up pin states at the end of the script:

GPIO.cleanup()

When the program exits, you may not want to clean up every channel and leave some settings. You can clean up individual channels, or clean up multiple channels using a list or tuple:

GPIO.cleanup(channel)
GPIO.cleanup( (channel1, channel2) )
GPIO.cleanup( [channel1, channel2] )

Raspberry Pi Board Information and RPi.GPIO Version

To view information about your Raspberry Pi board:

GPIO.RPI_INFO

To view the revision of the Raspberry Pi board:

GPIO.RPI_INFO['P1_REVISION']
GPIO.RPI_REVISION (deprecated)

To view the version of RPi.GPIO:

GPIO.VERSION

This Chinese tutorial is translated from croston’s raspberry-gpio-python tutorial, the original address is raspberry-gpio-python. This tutorial is for reference for those who are accustomed to using Chinese.

Due to the limited level of the translator, if there are errors, please feel free to correct them.