You can do a lot with a Raspberry Pi even if you limit yourself to what comes on the board. But if you’re willing and able to learn how to use the Pi’s general-purpose input/output pins — or GPIO pins, for short — then you’ll be able to do so much more. If you’re new to Raspberry Pi GPIO pins and Raspberry Pi GPIO pin projects, then this is the place to start: the very best GPIO tutorial that we could write.
Below, you’ll find an introduction to the concept of GPIO in general and to the Raspberry Pi‘s GPIO pins in particular. Explanations can only get us so far, though, so we’ll also dive into some DIY tinkering to get you acclimated to using the GPIO pins in your own projects. In our first project, we’ll set up a breadboard and LEDs and send them some code from our Raspberry Pi. In the second, we’ll use one of the several great pre-made Raspberry Pi accessories that take advantage of the GPIO pins. Both of these projects are suitable for beginners who have never messed around with GPIO pins before.
What’s with these GPIO pins, anyway?
If you already have a little familiarity with the Raspberry Pi‘s GPIO pins and want to dive into a simple DIY project, you can feel free to skip this section. The rest of us will run through some basics. This is our best GPIO tutorial, after all.
When it comes to the GPIO pins themselves, things are pretty much exactly what they appear to be. GPIO pins are little metal pins that can transmit signals but which are not “committed” (that is, not connected to anything outside of the circuit board they’re attached to — until you come along and change that, of course). Nothing in the GPIO pins themselves is specific to any particular sort of signal — hence the “general-purpose” part of the name — but that doesn’t mean that we can connect any old wire to them. The circuitry that GPIO pins end up attached to will have something to say about that! Depending on the board, these identical pins can serve very different purposes.
Let’s take a look at a Raspberry Pi device. As expected, we find our Raspberry Pi GPIO pins with one end attached to nothing (yet) and the other end firmly attached to the Raspberry Pi board. Each of the pins is connected to circuits on the board that care quite a bit about what enthusiastic DIYers may or may not decide to hook up to the pin in question. It’s important for us to know what purpose each GPIO pin serves on the Raspberry Pi.
Why? Because computers are delicate things, and because the signals that we send when we’re working with circuitry are electrical signals. Let too much juice flow through the wrong pin, and you’ll trash your Raspberry Pi.
Again, the pins are perfectly happy with whatever job they are assigned, but the circuit board (in this case, the Raspberry Pi) is what assigns them a job. If you hook up the wrong thing to the wrong GPIO pin, the pin will remain perfectly functional — and will happily pass along a signal that could fry the circuitry it’s attached to. Another important thing to remember: the pins are always the same and circuitry is what’s different, which by extension means that there is absolutely no guarantee that GPIO pins are doing the same jobs on different devices. We’re going to learn about using the GPIO pins on your Raspberry Pi, but you should absolutely not assume that the jobs are sorted out in the same manner for other sets of GPIO pins: the GPIO pins on an Arduino, for example, are not laid out in the same way or the same order.
The Raspberry Pi‘s GPIO pins
Okay, let’s talk Raspberry Pi GPIO pins.
Every member of the current Raspberry Pi lineup has a 40-pin “GPIO header” — a place to put GPIO pins — on it. Most models of Raspberry Pi also have the pins themselves. The exceptions are the Pi Zero and Pi Zero W, which have “unpopulated” (read: no pins!) GPIO headers. You can add pins to those yourself, though, if you’re up to doing a bit of soldering.
Here’s a map of what the 40 pins on modern Raspberry Pi devices do:
Image credit: Raspberry Pi Foundation
If you have one of the older Raspberry Pi models, you may have 26 pins instead of 40. Here’s how yours are laid out:
Image source: Raspberry Pi Foundation
Great, hope that clears everything up. Thanks for reading.
No, just kidding. We have more to talk about, of course. Like what “GPIO 12 (PWM1)” means, for example, or why we need all of these grounds. Remember this supposed to the best GPIO tutorial!
Power pins
Don’t worry, it doesn’t get too weird. We can start with the power pins, which include “3V3 power” and “5V power” pins. As those names suggest, these pins transmit power. Astute observers will notice that we already supply our Raspberry Pi with power via another source, so we can pretty easily see which way these power pins are sending the juice: It’s output, of course, meaning that we can do things like power peripherals.
It’s important to know that the pins labeled “5V” and “3V3” aren’t the only pins that can supply power. As we’ll soon see, we can command other pins to send some juice as output. These are just the pins that send out power by default. If you set up an LED circuit using a 3V3 pin, you’ll find that your LED lights up whenever the Pi is on, without you needing to program anything (in fact, you don’t even need to have a micro SD in your Raspberry Pi for this to work).
Grounds
And if we’re going to be rigging up electrical circuits here, we’ll need a ground. You’ll find grounds among the pins, too, of course — two types of pins down!
Standard GPIO pins
Take out the power and ground pins, and you’ll be left with the pins that are dedicated to sending output and receiving input. All of these can be used for straightforward input/output tasks, but they’re not all exactly the same. Some have the power to work with communications interfaces that others can’t handle, and some can send or receive power, too.
“Standard” GPIO pins are the most common ones on your board, and they’re capable of sending or receiving 3.3 volts. We’re going to make use of these pins in our DIY project in the second part of this Raspberry Pi GPIO tutorial.
Special pin powers
Some of the “regular” GPIO pins (the ones that aren’t power or ground pins) have special talents. We won’t deal much with these in basic DIY projects, but they may be good to know for more advanced uses.
SPI pins – SPI means serial peripheral interface, which is a communications interface best used with embedded system. In practice, this means that DIYers will use these pins to do things like connect touchscreen devices to their Raspberry Pi. The trick, though, is that you have to use all of them at once — meaning that devices that use SPI pins dominate your whole GPIO apparatus.
UART pins – UART stands for universal asynchronous receiver-transmitter, which is a physical circuit designed to send and recieve data. This is something that most DIYers won’t be messing around with.
PWM pins – PWM means “pulse width modification,” which is a communication protocol best used with stuff that moves and lights up: motors, LEDs, and so on.
I2C pins – I2c is short for inter-integrated circuit (that’s two “inters”). It works similarly to SPI, but it doesn’t force you to use nearly so many pins.
Programming GPIO pins
By now, we’ve figured out that GPIO pins can communicate inputs and outputs to and from a circuit board, and we’ve seen that the various sorts of inputs and outputs we have at our disposal are not all that specific: We can use them in different ways by telling our Raspberry Pi what to do with the inputs and when to send various types of outputs.
As you might imagine, the best way to do that is with a programming language. If you want to use the Raspberry Pi‘s GPIO pins in your programming, you have four main programming language options:
Scratch – Scratch is a visual programming language aimed at children. It’s primarily used for learning, though, and it’s not our best option for DIY stuff.
C/C++ – You can use GPIO inputs and outputs in C and C++ programming with either the standard kernel interface or the third-party library pigio.
Processing – Like Scratch, Processing is language designed to educate non-programmers.
Python – Here’s our superstar. The highly readable Python programming language is our best bet for using GPIO pins in our code, and it’s what we’ll use in the simple DIY project that we’ll work through in the next section.
Naming the pins
If we’re going to program with GPIO pins, we need a way to identify which pins we’re talking about. We’ll have options here, because every pin has two names. First, there’s the BOARD name, which refers to a given pin’s position on the Raspberry Pi board. Then there’s the BCM name. BCM stands for Broadcom SOC channel. The Raspberry Pi knows this naming system because Broadcom made its chip. You can use either name when you’re programming. The diagrams we looked at above sport the BOARD numbers, but you can translate those into BCM numbers pretty easily as long as you know what model of Raspberry Pi you’re looking at. You can even find a guide to both names using your Raspberry Pi itself: Just open Terminal and run the command pinout to see a map of the Raspberry Pi GPIO pins and their various names. (You can do this on Raspbian right out of the box, since it includes the required library — the GPIO Zero Python library — right out of the box. On Raspbian Lite and other operating systems, you may need to download that library before you can use the “pinout” command like this.)
Now that we know what GPIO pins are, how they work, and a little bit about how we might program them, we can do a simple DIY project to apply our new knowledge.
A simple Raspberry Pi GPIO tutorial project
It’s one thing to understand that GPIO pins can be used in code and DIY projects, and another thing to actually pull it off. To get ourselves acclimated, we’re going to start with this very straightforward GPIO pin tutorial project. We’re just going to control an LED on a broadboard with our Raspberry Pi and its GPIO pins. This is a pretty common project that’s generally considered to be the “Hello world” of Raspberry Pi GPIO pin projects, so it’s a great place to start if you’re new to all this.
When we’re all done with this, we’ll have our Raspberry Pi our LED, and a resistor connected in a circuit: We’ll have broadboard wire running from a standard GPIO pin to our broadboard and an LED, then our resistor, and then more wire back to a ground GPIO pin. We’ll have a Python script on our Raspberry Pi that will tell our standard GPIO pin to output 3.3 volts, and when we fire up this script we should see our light blink on. Simple enough, right? Let’s make it happen. First, let’s take a look at what you’ll need.
Parts list for this project
If you’d like to build this project yourself, here’s a handy parts list to get you started:
Got everything? Then let’s get started. First, we’ll set up our circuit.
Step 1: Turn off your Raspberry Pi
You don’t want to short anything out here, so let’s switch off that Pi, shall we? While it would be tough to hurt yourself with the kinds of charges we’re dealing with here, it’s all too easy to hurt your Pi. Switch that bad boy off to keep it safe.
Step 2: Set up your breakout kit
A breakout kit
While not technically required, this will make things much easier for you and a bit safer for your Raspberry Pi. A compatible breakout kit will attach to the GPIO pin apparatus on your Raspberry Pi and connect it via a belt to a new set of pins, which you can then stick right into your breadboard. Having the pins somewhere other than on your tiny Raspberry Pi board is nice, and having them labeled (as they should be on any breakout kit) is even nicer.
A brief mention of how breadboards work is important here. The holes in breadboards are connected to other holes by pieces of metal that run underneath the plastic bits. The holes with red and blue lines running along them are called the “rails,” and they’re connected parallel in the directions those lines run (but never across — the red and blue are two separate rails that run separate and parallel. The rows of holes closer to the center of the board are called “columns,” and they’re connected in rows — that is, perpendicular to the direction that the rails are running. The rails and columns are not connected, and the columns are not connected to the columns next to them. Nor are they connected to their counterparts across the little gap in the middle of the board (which is called the “valley”).
A breadboard
If you’re using a breakout kit, you’ll want to stick your breakout pins in such that they each get their own column. That means that the valley should run between the two sets of pins on your breakout set. Oh, and don’t forget to snap that bad boy in there (carefully, though) — it should go all the way into the breadboard.
Step 3: Connect a ground GPIO pin to the breadboard rail
If you’re familiar with breadboards, you’ll know that the “rail” is the line of holes marked in blue. The holes in the rail are all connected by a piece of metal that runs underneath them in the breadboard. Stick a breadboard wire into a hole on that rail.
Now take the other end of the wire and connect it to a ground pin on your Raspberry Pi. For those with modern Raspberry Pi models (the ones with 26 pins), that means either pin 6, 9, 14, 20, 25, 30, 34, or 39 (those are BOARD) numbers. If you’re using a breakout kit, this just means finding a hole in the same broadboard column as the ground pin.
Step 4: Use a resistor to connect the rail and any column on the breadboard
As you’ve probably noticed, we’re working backwards towards the power GPIO pin. That means our next stop is the resistor.
Stick the wire on one end of the resistor into the same rail that you used in Step 3. Then stick the other end in any column you want. The columns are the little rows of holes in the middle of the breadboard — in other words, the holes that aren’t on the rails. Any of those holes will do.
By the way, your resistor may be a pretty leggy boy. Feel free to trim the wires on each end a bit if you care about the aesthetics here.
Step 5: Connect the LED between the column with the resistor and a new column
Our next stop on our circuit is the star of the show: The LED. It matters which end of the LED wire you stick where on this step, so be careful.
One of the two wires sticking out of your LED should be longer than the other. It may also have a bend in it. That’s the one that we want to receive the Raspberry Pi‘s power output. That means the shorter end is going to go in the direction of the ground, which means that that’s the end we’ll want on the same rail as our resistor.
So go ahead and insert your LED with the shorter wire going into the rail with the resistor and the longer wire going into a new, unused column.
Step 6: Connect the LED’s column to a standard GPIO pin
The finished circuit in action. Note that the LED should be turned off on yours until you run the program.
We’re just about done here. All we have to do now is connect the LED to a GPIO pin that can provide it with 3.3 volts when we tell it to. A standard GPIO pin will work just fine for that, which means we can choose between 7, 11, 12, 13, 15, 16, 18, 22, 29, 31, 32, 33, 35, 36, 37, 38, and 40. Let’s agree to use the same one so that we can use the same code later on, okay? We’ll use pin 18.
Stick one end of a breadboard wire into a hole on the same column that you stuck the long LED wire into — that is, the one without the resistor.
Then connect the other end of that wire to pin 18 on your Raspberry Pi or breakout kit.
Step 7: Coding time!
We now have a simple circuit set up that runs from a potential power source (our Raspberry Pi‘s GPIO pin 18, which should currently not be sending any power) to an LED, then to a resistor, and then to a ground (another pin on our Raspberry Pi). If we give this thing some juice, the LED should light up.
And since we’re using GPIO pins, we have all kinds of control over if and when we’re powering up this circuit. We can write a little program that will light up this LED however we want — we could make it flash out Morse code, turn off and on to the beat of “Another One Bites the Dust,” or whatever else we dream up. For now, though, we’ll keep things simple. We’ll write a program that will turn on the LED, wait five seconds, and then turn it off again.
Let’s open nano!
So turn on your Raspberry Pi and then create a text file for your LED script. Using the nano text editor on Raspbian is a good option — to do that in Raspbian, just open up the Terminal and type “nano” followed by a text file name, like this: nano fun_with_LEDs.py.
Or, you know, whatever you want to call it.
Step 8: Writing the code and lighting the LED
The finished code as seen in nano
In the next step, we’ll break down our code to figure out how it’s working. But let’s have dessert before dinner and light up our LED first. Here’s what your finished code, which is written in Python, should look like. Note that the number 18 refers to the GPIO pin that we used back in Step 6 — if you used a different one, you should replace the code’s three references to 18 with the relevant number.
import RPi.GPIO as GPIO
import time
GPIO.setmode(GPIO.BCM)
GPIO.setwarnings(False)
GPIO.setup(18,GPIO.OUT)
print “The LED is on! Check it out!”
GPIO.output(18,GPIO.HIGH)
time.sleep(5)
print “Wasn’t that cool?”
GPIO.output(18,GPIO.LOW)
Save this file and you should be able to run the script by entering the command sudo python fun_with_LEDs.py (or, you know, whatever you called it) in Terminal on your Raspberry Pi. If everything is hooked up right, it should light up the LED, then turn it off again. It should also print some messages to the screen. If it didn’t work, check your code!
Step 9: Breaking down our code: How did this work?
This is our best effort at a GPIO tutorial, but there’s really nothing too crazy going on with the GPIO pins themselves. The real subjects of a GPIO tutorial are wiring up breadboards (check) and writing code that makes use of the GPIO pins. In most cases, that means we’re learning Python.
Python is super simple, so explaining the code above is pretty easy. Let’s go line by line.
import RPi.GPIO as GPIO – Our code is read by a Python “interpreter,” which is, as the name suggests, a program that knows how to read Python. But our Raspberry Pi‘s specific GPIO pin layout is not the sort of thing that would be important to include in a universal programming language or its interpreter. If we just start telling it to fire up pins, it won’t know what we’re talking about. That’s why we use this line to import a “library,” which is basically just an expansion pack of Python goodies. Now we’ll be able to use commands that we couldn’t before.
import time – Another library! This time, we’re importing the time library. This will let us use the Raspberry Pi‘s internal clock in our code.
GPIO.setmode(GPIO.BCM) – This looks like one of the weirder lines, but it’s pretty simple. There are two naming conventions for GPIO pins that Python (with our added GPIO library) will understand. We talked about this up above in the Programming GPIO pins section, which came right before this step-by-step DIY project section.
GPIO.setwarnings(False) – Python might have some GPIO warning messages for us, but we live dangerously and don’t care about those, right? Right. This makes sure that they aren’t printed to the screen while we’re enjoying our beautiful program.
GPIO.setup(18,GPIO.OUT) – We’re setting things up here! GPIO.setup takes two arguments: a pin number and what we’re using it for. The number here should correspond to the GPIO pin we’re using, and we want GPIO.OUT because we want output, not input.
print “The LED is on! Check it out!” – This prints a message to our screen. The message is not true yet, strictly speaking, but it will be true almost instantly.
GPIO.output(18,GPIO.HIGH) – We’re outputting something over the GPIO pins. GPIO.output takes two arguments. The first is a pin number. We can put our buddy in there because we set him up for output a couple of lines of code ago. The second is the output, which in this case is GPIO.HIGH. A HIGH output for a standard GPIO pin is 3.3 volts. The net result here is that our LED turns on. We are liars no more!
time.sleep(5) – Good thing we imported that time library in the second line of our code. Now our interpreter knows how to read this time command, which tells our program to take a snooze for five seconds. As the program pauses, everything stays as it was — which means the power GPIO pin keeps outputting juice to the LED, and we can admire our handiwork.
print “Wasn’t that cool?” – We’re printing things to the screen again. Wasn’t it cool to see the light turn off and then on again, we ask, even though the light is actually still on? Don’t worry about the little fib. The light will be off before you know it.
GPIO.output(18,GPIO.LOW) – And just like that, the LED goes out again. This is our GPIO.output command again, taking the same arguments as last time but, this time around, going with GPIO.LOW as the output. That means 0 volts.
If that all seemed pretty simple, that’s because it was! Python is a very straightforward language that stresses readability and make liberal use of libraries. Of course, you could easily build on this project by setting up a more complicated circuit (or multiple circuits) and writing more interesting code. That’s all up to you! For the purposes of our Raspberry Pi GPIO tutorial, though, we’ll call it quits here.
GPIO pins and Raspberry Pi accessories
In the project that we just ran through, we were able to set up a broad board, wires, and LEDs and connect that apparatus to our Raspberry Pi using the GPIO pins. Our project was simple, but it didn’t necessarily have to be. With the right know-how, we could build really elaborate circuits to rig up to our Raspberry Pi via the GPIO pins.
You can probably see the implications here. The GPIO pins don’t much care if they’re attached to simple things or complex ones, and they also don’t care if they’re rigged up to DIY projects or to professionally manufactured circuits. While we here at TheGeekPub admire your individualism and self-reliance, it is all the same to the GPIO pins. So it’s no surprise that there are a ton of manufactured Raspberry Pi peripherals that make use of the GPIO pins. You could find yourself messing with GPIO pins while attaching a touchscreen, for example, and you’d never have to pick up a breadboard or wires.
There are lots of these sorts of accessories, but we’ll pick one here to use as an example here in our Raspberry Pi GPIO tutorial: the sense HAT.
Meet the sense HAT
The sense HAT
The sense HAT looks like a little circuit board with some stuff attached to it — a bit like the Raspberry Pi, actually. The sense HAT, though, was always intended as an add-on board to the Raspberry Pi and does not work on its own. The device was originally developed for the Astro Pi project, which gave students the chance to play a part in space research: They were tasked with writing programs that would make use of the sense HAT and which (if selected) would run on a Raspberry Pi-sense HAT setup on the International Space Station.
You don’t have to be in Space to get something out of this device, though. The sense HAT has sensors that can measure temperature, humidity, pressure, and the orientation of the board. It also boasts a matrix of LEDs.
The sense HAT communicates information using the GPIO pins — which, of course, is why we’re talking about it here. The sense HAT is designed to fit right on top of a Raspberry Pi device, with the Pi’s GPIO pins poking into a 40-pin GPIO header on the sense HAT.
Grab this accessory, and you’ll have even more DIY options. You could use the LED matrix to set up a digital clock, for instance, or you could use the sensors on the sense HAT to take stock of the weather and then beam that information to your computer or another device using the Raspberry Pi‘s Wi-Fi capabilities. There’s tons to do, and it’s all thanks to the Raspberry Pi‘s GPIO pins.
A simple Raspberry Pi sense HAT tutorial project
Earlier in this GPIO tutorial, we programmed GPIO pins for use with a broadboard circuit. Now, let’s try a project that uses a professionally manufactured accessory. We’re going to have the sense HAT measure the temperature and then print the result to our screen — a super-simple task that won’t take us long at all. Here’s what you’ll need:
Parts list for this project
If you’d like to build this project yourself, here’s a handy parts list to get you started:
Raspberry Pi with 40 GPIO pins (any model since 2014)
Raspberry Pi power supply
Compatible HDMI cable (and a monitor or TV to connect it to)
micro SD card with Raspbian disk image installed
sense HAT
Let’s get started.
Step 1: Attach your sense HAT to your Raspberry Pi
With your Raspberry Pi turned off, fit your sense HAT onto your Raspberry Pi.
The sense HAT is designed to sit right on top of a modern Raspberry Pi‘s 40-pin GPIO apparatus. The pins will poke right into a 40-pin header on the sense HAT. You can stabilize everything with the screws and little columns that should have been included with the sense HAT.
Step 2: Install the sense HAT software
If you haven’t already done so, hop into Terminal on Raspbian and enter these commands to update Raspbian (always a good idea), install the sense HAT software, and reboot your Raspberry Pi:
Turn on your Raspberry Pi, because it’s time to code! Open up a text file. As in our first DIY project, using nano is a good idea. You can do that by typing “nano” into a Terminal window and appending it with the name you want to give your file, like this: nano Temp_Time.py (or, you know, whatever you want to call it).
Here’s the code we’ll use:
from sense_hat import SenseHat
sense = SenseHat()
sense.clear()
temp = sense.get_temperature()
print(“It is {} degrees Celcius”.format(temp))
Now you can run your code with the command sudo python Temp_Time.py (or whatever you want to call it). The temperature should be printed to the screen. We’re already done!
Step 4: Understanding our code
Let’s take a closer look at the code that we just used so that we’re sure we understand it. It’s worth nothing one thing about this code that you may not have expected: It makes no mention of the GPIO pins!
Because the sense HAT has its own library, we can import a bunch of commands that tell our Raspberry Pi and sense HAT to communicate using the GPIO pins without actually having to get our hands dirty directing all the traffic. When we type sence.get_temperature(), our Python interpreter knows to get the temperature from the sense HAT. That information is sent to the Raspberry Pi itself via a GPIO pin, of course, but we don’t have to know the specifics. These are the virtues of using fancy accessories instead of breadboards.
Here are the details, line by line:
from sense_hat import SenseHat – this imports the sense HAT library for Python, which makes our task here very, very easy.
sense = SenseHat() – This is a Python thing called “object instantiation.” We’re taking the SenseHat() class (a class is a group of related things in Python) and assigning the variable “sense.” Now we can reference the sense hat class in our commands using “sense” followed by the dot operator (just a period: “.”) and then the command we want.
sense.clear() – This command just clears out old junk that might have been displayed on our sense HAT’s LED matrix. We know we’re talking about the sense HAT because we use the sense variable that we just defined.
temp = sense.get_temperature() – as you can probably guess, sense.get_temperature() is a command that gets the current temperature from the sense HAT. The “temp =” part defines a variable. The “sense.” part indicates that we’re working with the sense HAT and its library. So this line just stores the current temperature as a variable called “temp.”
print(“It is {} degrees Celcius”.format(temp)) – this takes the value of the variable “temp,” which we just set to be the current temperature, and prints it to the screen within a text string. Python lets us use “{}” and the .format function to pull off this trick.
And that’s it. Pretty simple, right?
Going further
Writing the best GPIO tutorial we could meant using DIY projects as examples, but we have kept things really, really simple here. You might be itching to do something more — and that’s great! The Raspberry Pi GPIO pins are the device’s Swiss Army knife, and their uses are nearly as unlimited as your imagination. Move on to other, trickier Raspberry Pi GPIO DIY projects explained on this site and others, or come up with your own! What you do next is up to you, because you’ve reached the end of our GPIO tutorial.
Upgrade to Premium
If you like our content maybe consider upgrading to Premium. You’ll get access to
In the naming pins section you mention ‘the GPIO Zero Python library’ , but your code in step 8 uses the RPi.GPIO library. Is one better than the other?
7 Responses
5
This was really well written! Thank you! I just have one question. How much power can the GPIO deliver?
In the naming pins section you mention ‘the GPIO Zero Python library’ , but your code in step 8 uses the RPi.GPIO library. Is one better than the other?
0.5
1.5
5
2.5