7 days of unlimited WordPress themes, plugins & graphics - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Computer Skills
  2. Electronics

Learn How to Use Raspberry Pi GPIO Pins With Scratch

Scroll to top
Read Time: 6 mins

In this tutorial, I'll show you how to install the ScratchGPIO expansion package, how to assemble a breadboard with LEDs and buttons, and run a simple Scratch game that uses the LEDs and breadboard buttons to play.


With the Raspberry Pi's emphasis on education it makes perfect sense that Scratch is pre-installed on the default Raspbian build and available as an icon on the desktop.

Simon Walters, @cymplecy on Twitter, has created an expansion for Scratch that allows your program to read and write the status of the Raspberry Pi GPIO Pins. Simon blogs about his creation, ScratchGPIO at Cymplecy and continues to maintain it on his github repository.

Gather the Components

Assemble the Breadboard

The breadboard will house the LEDs and the buttons with witch ScratchGPIO will interact. The LEDs need a current limiting resistor of 220 OHMs and the buttons need the 1K OHM resistors to ensure the pins do not pass too much current.

Using the image below, setup the breadboard and jumpers to the GPIO pins shown in the diagram. The pin numbers that the GPIO module and Scratch code use are the physical pin numbers not GPIO or logical numbers. Refer to the images on the RPi Low-level peripherals page to identify the pin numbers.

  • Connect the button leads from physical pins 3 and 5 to the buttons on the breadboard as show below. These pins are designated as input by default in the ScratchGPIO software.
  • Connect the Red, Yellow, and Green LEDs on the breadboard to the Pi's physical pins 11, 12, and 13 which are designated as output pins by ScratchGPIO.
  • Ensure the proper resistors are on the breadboard. The 220 ohm resistors are for the LEDs and the 1K ohm resistors are for the buttons.
Assembled Breadboard Diagram

Setup the Raspberry Pi

There are several guides to purchasing and installing an OS on your Raspberry Pi. Install the latest Raspbian operating system. Once your Raspberry Pi is configured and booted up to the graphical desktop move on to the next step.

Install ScratchGPIO

The ScratchGPIO software does not change or replace scratch, it adds a set of python scripts that integrate with Scratch and add the ability to control and read the GPIO pins at the hardware level. Scratch will continue to function as normal after the install.

There will, however, be a new icon on the graphical desktop of the Raspberry Pi that will launch the GPIO support scripts and Scratch together. The installer is simple and easy to use. Follow the instructions below to download and install the ScratchGPIO package.

  • Double click and launch LXTerminal
  • Execute the following commands:
  • The installer script will complete politely saying Thank You and Finished. Saying You're welcome is optional but certainly the polite thing to do.
  • Close the LXTerm window and notice the new icon titled: Scratch GPIO4

Get the Scratch Example Program

The topic of writing Scratch programs is deep and wide. This tutorial does not cover the details of Scratch programming, but the Scratch website does an excellent job with introducing and teaching Scratch if you want to learn more.

In the steps below you will download and run a scratch game that takes advantage of the GPIO extensions and the breadboard setup you built. The game sets the output pins 11, 12, and 13 high to light the LEDs and show the health of the game's hero, Cat.

As Cat loses health the LEDs are turned off one by one until they are all dark and the game is over. During the game play, the program checks the status of the input pins 3 and 5 and when the pins are low, or grounded, Cat moves up and down to try to avoid the charging opponent, Rex.

  • Launch Midori from the desktop of your Raspberry Pi
  • Download the gpiogame.sb Scratch file
  • Save the downloaded file to /home/pi/scratch/Documents/Scratch Projects
  • Close Midori
  • Launch Scratch GPIO4 from the desktop
  • Click OK on the dialog box that says Remote sensor connections enabled. This message indicates that Scratch is communicating with the GPIO subsystem.
  • Select File > Open
  • Select the file gpiogame to load the game
  • Click on the Green Flag on the upper right corner of the Scratch window to start the game
  • Press the buttons on the breadboard to help Cat avoid Rex. Click the green flag again if you want to restart the game.

As you play the game you will see how the three LEDs on the breadboard reflect the health level of Cat and that the buttons indeed move Cat up and down. I'll point out the bits of code that interact with the Pi GPIO pins, below. For reference you can find full documentation on the ScratchGPIO package on the authors blog.

The LEDs are powered when the pins they are connected to are turned high or on. The LED will glow and the resistor will prevent too much current from passing. Click on the Stage icon in the lower left panel of the Scratch window. This will bring the script for the stage object into the editor in the center of the window.

The code snippet below is the LED and health handling routine. When the code block receives the UpdateHealth broadcast message, it assesses the health variable and sets the pins low when health is lost.

LED Health Handling Routine

The momentary push buttons connect pins 3 and 5 to ground through the current limiting resistor when pressed. The Raspberry Pi then recognizes the pin as low or 0 in Scratch. Click on the cat icon in the lower right pane of the window to bring the code for it into the middle pane.

In the top code block, after some setup housekeeping, the code loops checking the status of pins 3 and 5. When either is detected to be low or 0, the message up or down is sent. Lower in the cat script are code blocks that receive the directional messages and move the sprite itself.

Button Handling Routine

My high score was 34. See if you can beat that!

High Score Brag


Scratch is a very accessible and easy to learn programming framework for both young children and adults. Its close association with the Raspberry Pi and its educational emphasis has been a perfect match. The ScratchGPIO project brings control and sensing of the Pi's low level GPIO pins to Scratch in a very powerful way. The author continues to enhance the package to support LCD screens, motors, compass components, distance sensors, and other electronic and robotic components.

The level of hardware control offered by the ScratchGPIO package allows even beginner programmers the ability to interact with the physical world with a simple and familiar programming framework.

By following this tutorial you've learned how to install the ScratchGPIO package, where to look for more information about it and Scratch. In addition, you've assembled an easy to use breadboard circuit that will allow you to safely experiment with Scratch and GPIO control for both input and output.

Finally, you installed a game that can be used as an example and a basis to be modified to learn and experiment. As the ScratchGPIO project continues to mature and expand you can look forward to seeing a whole new generation of Raspberry Pi robotics controlled by Scratch.

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Computer Skills tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.