Build Physical Projects With Python on the Raspberry Pi

Raspberry Pi Board Overview

The Raspberry Pi comes in a variety of form factors for different use cases. In this tutorial, you’ll be looking at the most recent version, the Raspberry Pi 4 .

Below is the board layout of the Raspberry Pi 4. While this layout is slightly different from previous models of the Raspberry Pi, most of the connections are the same. The setup described in the next section should be the same for both a Raspberry Pi 3 and a Raspberry Pi 4:

The Raspberry Pi 4 board contains the following components:

• General-purpose input–output pins:These pins are used to connect the Raspberry Pi to electronic components.

• Ethernet port:This port connects the Raspberry Pi to a wired network. The Raspberry Pi also has WiFi and Bluetooth built in for wireless connections.

• Two USB 3.0 and two USB 2.0 ports:These USB ports are used to connect peripherals like a keyboard or mouse. The two black ports are USB 2.0 and the two blue ports are USB 3.0.

• AV jack:This AV jack allows you to connect speakers or headphones to the Raspberry Pi.

• Camera Module port:This port is used to connect the official Raspberry Pi Camera Module , which enables the Raspberry Pi to capture images.

• HDMI ports:These HDMI ports connect the Raspberry Pi to external monitors. The Raspberry Pi 4 features two micro HDMI ports, allowing it to drive two separate monitors at the same time.

• USB power port:This USB port powers the Raspberry Pi. The Raspberry Pi 4 has a USB Type-C port, while older versions of the Pi have a micro-USB port.

• External display port:This port is used to connect the official seven-inch Raspberry Pi touch display for touch-based input on the Raspberry Pi.

• microSD card slot (underside of the board):This card slot is for the microSD card that contains the Raspberry Pi operating system and files.

A little later in this tutorial, you’ll use the components above to set up your Raspberry Pi.

Raspberry Pi vs Arduino

People often wonder what the difference is between a Raspberry Pi and an Arduino. The Arduino is another device that is widely used in physical computing. While there is some overlap in the capabilities of the Arduino and the Raspberry Pi, there are some distinct differences.

The Arduino platform provides a hardware and software interface for programming microcontrollers . A microcontroller is an integrated circuit that allows you to read input from and send output to electronic components. Arduino boards generally have limited memory, so they’re often used to repeatedly run a single program that interacts with electronics.

The Raspberry Pi is a general-purpose, Linux-based computer. It has a full operating system with a GUI interface that is capable of running many different programs at the same time.

The Raspberry Pi comes with a variety of software preinstalled, including a web browser, an office suite, a terminal, and even Minecraft. The Raspberry Pi also has built-in WiFi and Bluetooth to connect to the Internet and external peripherals.

For running Python, the Raspberry Pi is often the better choice, as you get a full-fledged Python installation out of the box without any configuration.

Required Hardware

The following hardware is required for the initial setup of your Raspberry Pi. If you end up connecting to your Raspberry Pi over SSH, which you’ll look atlater in this tutorial, then some of the hardware below will not be needed after the initial setup.

Optional Hardware

You can use a whole range of additional hardware with the Raspberry Pi to extend its capabilities. The hardware items listed below are not required to use your Raspberry Pi but would be useful to have on hand.

Software

The operating system for the Raspberry Pi is stored on a microSD card. If your card did not come from an official Raspberry Pi kit, then you’ll need to install the operating system on it.

There are multiple ways to set up the operating system on your Raspberry Pi. You can find out more about the different installation options on the Raspberry Pi website .

In this section, you’ll look at two ways to install Raspbian , the officially supported Raspberry Pi operating system, which is based on Debian Linux.

Final Setup

Now that you have the microSD card and required hardware ready, the final step is to connect everything together and configure the operating system. Let’s start off by connecting all the peripherals:

1. Insert the microSD card into the card slot on the bottom of the Raspberry Pi.
2. Connect the keyboard and mouse to any of the four USB ports.
3. Connect a display to one of the HDMI ports using an HDMI cable specific to your Raspberry Pi model.
4. Connect a power supply to the USB power port.

With the peripherals connected, go ahead and power on your Raspberry Pi to configure the operating system. If you installed Raspbian with the Raspberry Pi Imager, then there’s nothing else for you to do. You can skip down to theto complete the setup.

If you installed NOOBS on your SD card, then you’ll need to complete a couple more steps to install Raspbian on the SD card:

1. First, power on the Raspberry Pi to load the NOOBS interface.
2. Then, check the checkbox next to the Raspbian option in the list of software to install.
3. Finally, click the Install button at the top left corner of the interface to begin installing Raspbian on the SD card.

Once the installation is complete, the Raspberry Pi will restart, and you’ll be booted into Raspbian to complete the setup wizard.

Using the Mu Editor

The Raspbian operating system comes with several preinstalled Python IDEs that you can use to write your programs. One of these IDEs is Mu . It can be found in the main menu:

Raspberry Pi Icon → Programming → Mu

When you open Mu for the first time, you’ll be given the option to select the Python mode for the editor. For the code in this tutorial, you can select Python 3 :

There’s a chance that Mu may not be preinstalled on your version of Raspbian. If Mu isn’t installed, then you can always install it by going to the following file location:

Raspberry Pi Icon → Preferences → Recommended Software

This will open up a dialogue containing recommended software for your Raspberry Pi. Check the box next to Mu and click OK to install it:

While Mu provides a great editor to get started with Python on the Raspberry Pi, you may want something more robust. In the next section, you’ll connect to your Raspberry Pi over SSH.

Editing Remotely Over SSH

Often you won’t want to spend the time hooking up a monitor, keyboard, and mouse to write Python on the Raspberry Pi. Luckily, Raspbian allows you to connect to the Raspberry Pi remotely over SSH . In this section, you’ll learn how to enable and use SSH to program Python on the Raspberry Pi.

pi@raspberrypi:~ $ hostname -I

$ ssh pi@[IP ADDRESS]

pi@raspberrypi:~ $

pi@raspberrypi:~ $ python3

>>> print("Hello from your Raspberry Pi!")
Hello from your Raspberry Pi!

Creating a python-projects Directory

Before you start building projects with Python on the Raspberry Pi, it’s a good idea to set up a dedicated directory for your code. The Raspberry Pi has a full file system with many different directories. Having a reserved place for your Python code will help keep everything organized and easy to find.

Let’s create a directory called python-projects where you can store Python code for your projects.

$ ssh pi@[IP ADDRESS]

pi@raspberry:~ $

pi@raspberry:~ $ pwd
/home/pi

pi@raspberry:~/Desktop $ cd /home/pi
pi@raspberry:~ $ pwd
/home/pi

pi@raspberry:~ $ mkdir python-projects

pi@raspberry:~ $ cd python-projects
pi@raspberry:~/python-projects $

Electronic Components

Before programming on the Raspberry Pi, you’ll need a few electronic components to build the projects in the upcoming sections. You should be able to find each of the items below on Amazon or at your local electronics store.

GPIO Pins

The Raspberry Pi features forty GPIO pins along the top edge of the board. You can use these GPIO pins to connect the Raspberry Pi to external components.

The pin layout below shows the different types of pins and their locations. This layout is based on an overhead view of the pins with the Raspberry Pi’s USB ports facing you:

The Raspberry Pi features five different types of pins:

1. GPIO: These are general-purpose pins that can be used for input or output.
2. 3V3: These pins supply a 3.3 V power source for components. 3.3 V is also the internal voltage that all GPIO pins supply.
3. 5V: These pins supply a 5 V power source, the same as the USB power input that powers the Raspberry Pi. Some components, such as the passive infrared motion sensor, require 5 V.
4. GND: These pins provide a ground connection for circuits.
5. ADV: These special-purpose pins are advanced and not covered in this tutorial.

In the next section, you’ll use these different pin types to set up your first component, a tactile button.

Tactile Button

For your first circuit, you’re going to connect a tactile button to the Raspberry Pi. A tactile button is an electronic switch that, when pressed, closes a circuit. When a circuit is closed, the Raspberry Pi will register an ON signal. You can use this ON signal to trigger different actions.

In this project, you’ll use a tactile button to run different Python functions based on the state of the button. Let’s start by wiring the button to the Raspberry Pi:

1. Connect a female-to-male jumper wire from the Raspberry Pi’s GND pin to the negative rail of the breadboard.
2. Place a tactile button across the gutter in the middle of the breadboard.
3. Connect a male-to-male jumper wire from the negative rail of the breadboard to the row where the button’s bottom-left leg is placed.
4. Connect a female-to-male jumper wire from the Raspberry Pi’s GPIO4 pin to the breadboard row where the button’s bottom-right leg is placed.

You can confirm your wiring with the diagram below:

Now that you’ve got your circuit wired up, let’s write the Python code to read input from the button.

Note:If you’re having trouble finding a specific pin, then make sure to reference theGPIO pin layout imagewhen building your circuits. You can also purchase a breakout board for easy breadboarding.

Inside the python-projects directory that you created earlier, save a new file called button.py . If you’re using SSH to access your Raspberry Pi, then create the file like this:

pi@raspberrypi:~/ cd python-projects
pi@raspberrypi:~/python-projects $ touch button.py

If you’re using Mu, then create the file with the following steps:

1. Click the New menu item.
2. Click Save .
3. Navigate to the /home/pi/python-projects directory.
4. Save the file as button.py .

With the file created, you’re ready to start coding. Start by importing the Button class from the gpiozero module. You’ll also need to import pause from the signal module. You’ll look at why you need pause later:

from gpiozero import Button
from signal import pause

Create an instance of the Button class and pass the pin number as a parameter. In this case, you’re using the GPIO4 pin, so you’ll pass in 4 as the parameter:

button = Button(4)

Next, define functions that will be called for the different button events that are available on a Button instance:

def button_pressed():
    print("Button was pressed")

def button_held():
    print("Button was held")

def button_released():
    print("Button was released")

The Button class has three event properties: .when_pressed , .when_held , and .when_released . These properties can be used to hook up different event functions.

While the .when_pressed and .when_released properties are self-explanatory, .when_held requires a short explanation. If a function is set to the .when_held property, then it will only be called if the button is pressed and held for a certain amount of time.

The hold time for .when_held is determined by the .hold_time property on the Button instance. The default for .hold_time is one second. You can override this by passing a float value when creating a Button instance:

button = Button(4, hold_time=2.5)
button.when_held = button_held

This will create a Button instance that will wait two and a half seconds after the button is pressed and held before calling the button_held() function.

Now that you know about the different event properties on Button , set each of these to their respective functions that you defined earlier:

button.when_pressed = button_pressed
button.when_held = button_held
button.when_released = button_released

Great! You’ve got your button events set up. The last thing you need to do is to call pause() at the end of the file. Calling pause() is required to keep the program listening for the different events. If this wasn’t present, then the program would run once and exit.

Your final program should look like this:

from gpiozero import Button
from signal import pause

button = Button(4)

def button_pressed():
    print("Button was pressed")

def button_held():
    print("Button was held")

def button_released():
    print("Button was released")

button.when_pressed = button_pressed
button.when_held = button_held
button.when_released = button_released

pause()

With the wiring complete and the code all set up, you’re ready to try out your first circuit. Inside of the python-projects directory, run the program:

pi@raspberrypi:~/python-projects $ python3 button.py

If you’re using Mu, first make sure the file is saved, then click Run to start the program.

The program is now running and listening for events. Press the button, and you should see the following in the console:

Button was pressed

Press and hold the button for at least one second, and you should see the following output:

Button was held

Finally, when you release the button you should see the following:

Button was released

Awesome! You’ve just wired and coded your first circuit using Python on the Raspberry Pi.

Since you used pause() in your code, you’ll need to manually stop the program. If you’re running the program in Mu, then you can click Stop to quit the program. If you’re running this from the command line, then you can stop the program with Ctrl + C .

With this first circuit under your belt, you’re ready to start controlling some other components.

LED

For your next circuit, you’ll use Python to blink an LED on and off every second. LED stands for light-emitting diode , and these components produce light when a current is applied. You’ll find that they’re used everywhere in electronics.

Every LED has two legs. The longer leg is the positive leg, or anode . The electrical current enters the LED through this leg. The shorter leg is the negative leg, or cathode ). The current exits the LED through this leg.

Current can only flow one direction through an LED, so make sure you’re connecting jumper wires to the proper leg of the LED.

Here are the steps you’ll need to take to wire this circuit:

1. Connect a female-to-male jumper wire from the Raspberry Pi’s GND pin to the negative rail of the breadboard.

2. Place an LED into two holes on the breadboard that are next to each other but not in the same row.

3. Place the longer, positive leg of the LED into the hole on the right side.

4. Place the shorter, negative leg of the LED into the hole on the left side.

5. Place one end of a 330 Ω resistor into a hole in the same breadboard row as the negative leg of the LED.

6. Place the other end of the resistor into the negative rail of the breadboard

7. Connect a female-to-male jumper wire from the Raspberry Pi’s GPIO4 pin to a hole in the same breadboard row as the positive leg of the LED.

You can confirm your wiring with the diagram below:

If the wiring looks good, then you’re ready to write some Python to get the LED blinking. Start by creating a file for this circuit inside of the python-projects directory. Call this file led.py :

pi@raspberrypi:~/python-projects $ touch led.py

In this code, you’ll create an instance of the LED class and call its .blink() method to make the LED blink on and off. The .blink() method has a default timeout of one second. The LED will continue to blink on and off every second until the program is exited.

Start by importing LED from the gpiozero module and pause from the signal module:

from gpiozero import LED
from signal import pause

Next, create an instance of LED called led . Set the GPIO pin to 4 :

led = LED(4)

Call the .blink() method on led :

led.blink()

Finally, add a call to pause() to make sure the program doesn’t exit:

pause()

Your complete program should look like this:

from gpiozero import Buzzer
from signal import pause

led = LED(4)
led.blink()

pause()

Save the file and run it to see the LED blink on and off:

pi@raspberrypi:~/python-projects $ python3 led.py

The LED should now be blinking on and off every second. When you’re done admiring your Python code in action, stop the program with Ctrl + C or Stop in Mu.

Now you know how to control an LED with Python on the Raspberry Pi. For the next circuit, you’ll be using Python to produce sound from the Raspberry Pi.

Buzzer

In this circuit, you’ll be wiring an active piezo buzzer to the Raspberry Pi. A piezo buzzer emits a tone when current is applied. Using this component, your Raspberry Pi will be able to generate sound.

Like LEDs, a buzzer has a positive and negative leg. The positive leg of the buzzer will either be longer than the negative leg or there will be a positive sign ( + ) on the top of the buzzer showing which leg is the positive leg.

Let’s go ahead and wire up the buzzer:

1. Place a buzzer on the breadboard, noting the placement of the buzzer’s positive leg .

2. Connect a female-to-male jumper wire from the Raspberry Pi’s GND pin to a hole in the same breadboard row as the negative leg of the buzzer.

3. Connect a female-to-male jumper wire from the Raspberry Pi’s GPIO4 pin to a hole in the same breadboard row as the positive leg of the buzzer.

Confirm your wiring against the diagram below:

With the wiring set up, let’s move on to the code. Create a file for this circuit inside the python-projects directory. Call this file buzzer.py :

pi@raspberrypi:~/python-projects $ touch buzzer.py

In this code, you’ll create an instance of the Buzzer class and call it’s .beep() method to make the buzzer beep on and off. The .beep() method’s first two parameters are on_time and off_time . These parameters take a float value to set how long the buzzer should beep on and off. The default value for both is one second.

Start by importing Buzzer from the gpiozero module and pause from the signal module:

from gpiozero import Buzzer
from signal import pause

Next, create an instance of Buzzer called buzzer . Set the GPIO pin to 4 :

buzzer = Buzzer(4)

Call the .beep() method on buzzer . Set the on_time and off_time parameters to 0.5 . This will make the buzzer beep every half second:

buzzer.beep(0.5, 0.5)

Finally, add a call to pause() to make sure the program doesn’t exit:

pause()

Your complete program should look like this:

from gpiozero import LED
from signal import pause

buzzer = Buzzer(4)
buzzer.beep(0.5, 0.5)

pause()

Save the file and run it to hear the buzzer beep on and off every half second:

pi@raspberrypi:~/python-projects $ python3 buzzer.py

You should hear the buzzer sound on and off until you stop the program with Ctrl + C or Stop in Mu.

Note:If you’re using Mu, then there’s a chance that when you stop the program the tone will continue. To stop the sound, remove the GND wire to break the circuit.

You may also need to restart Mu if the tone continues when you reconnect the GND wire.

Great! So far you’ve learned how to control three different types of electronic components with Python on the Raspberry Pi. For the next circuit, let’s take a look at a slightly more complex component.

Motion Sensor

In this circuit, you’ll be connecting a passive infrared (PIR) motion sensor to the Raspberry Pi. A passive infrared motion sensor detects any motion in its field of vision and sends a signal back to the Raspberry Pi.

pi@raspberrypi:~/python-projects $ touch pir.py

from gpiozero import MotionSensor
from signal import pause

motion_sensor = MotionSensor(4)

def motion():
    print("Motion detected")

def no_motion():
    print("Motion stopped")

print("Readying sensor...")
motion_sensor.wait_for_no_motion()
print("Sensor ready")

motion_sensor.when_motion = motion
motion_sensor.when_no_motion = no_motion

pause()

pir = MotionSensor(4, threshold=0.2)

pi@raspberrypi:~/python-projects $ python3 pir.py
Readying sensor...
Sensor ready

Motion detected

Motion stopped

Wiring

Here are the steps to complete the wiring:

1. Connect female-to-male jumper wires from the Raspberry Pi’s 5V and GND pins to the positive and negative rails on the side of the breadboard.

2. Place an LED on the breadboard and connect the Raspberry Pi’s GPIO14 pin to the LED with a female-to-male jumper wire.

3. Connect the LED’s negative leg to the breadboard’s negative rail through a 330 Ω resistor .

4. Place a buzzer on the breadboard and connect the Raspberry Pi’s GPIO15 pin to the buzzer with a female-to-male jumper wire.

5. Connect the buzzer’s negative leg to the breadboard’s negative rail with a male-to-male jumper wire.

6. Connect a female-to-male jumper wire from the breadboard’s positive rail to the sensor’s VCC pin.

7. Connect a female-to-female jumper wire from the Raspberry Pi’s GPIO4 pin to the sensor’s OUT pin.

8. Connect a female-to-male jumper wire from the breadboard’s negative rail to the sensor’s GND pin.

Confirm the wiring against the diagram below:

Okay, now that you have the circuit wired up, let’s dig into the Python code to set up your motion-activated alarm system.

Code

As usual, start by creating a file for this project inside the python-projects directory. For this project, call this file motion_detector.py :

pi@raspberrypi:~/python-projects $ touch motion_detector.py

The first thing you want to do is import the csv module so you can save a timestamp when motion is detected. Also, import Path from the pathlib module so you can reference your CSV file:

import csv
from pathlib import Path

Next, import datetime from the datetime module so you can create a timestamp of the motion event:

from datetime import datetime

Finally, import the required component classes from gpiozero as well as pause from the signal module:

from gpiozero import LED, Buzzer, MotionSensor
from signal import pause

With the imports ready, you can set up the three electronic components you’ll be using. Create instances of the LED , Buzzer , and MotionSensor classes. For each of these, pass in their pin numbers as parameters:

led = LED(14)
buzzer = Buzzer(15)
motion_sensor = MotionSensor(4)

Next, define the location of a CSV file that will store a timestamp each time motion is detected. You’ll call it detected_motion.csv . Create a dictionary to hold the timestamp values that will be written to the CSV:

output_csv_path = Path("detected_motion.csv")
motion = {
    "start_time": None,
    "end_time": None,
}

Create a method that saves the timestamp data to a CSV file. When the file is first created, a header row is added:

def write_to_csv():
    first_write = not output_csv_path.is_file()

    with open(output_csv_path, "a") as file:
        field_names = motion.keys()
        writer = csv.DictWriter(file, field_names)
        if first_write:
            writer.writeheader()
        writer.writerow(motion)

Define a start_motion() function. This function will have several behaviors:

• Start blinking the led on and off every half second
• Make the buzzer beep
• Save the start_time timestamp to the motion dictionary

Add a call to print() so you can watch the events occur while the program is running:

def start_motion():
    led.blink(0.5, 0.5)
    buzzer.beep(0.5, 0.5)
    motion["start_time"] = datetime.now()
    print("motion detected")

Then define an end_motion() function that will have the following behaviors:

• Turn off the led and buzzer
• Save the end_time timestamp
• Call write_to_csv() to save the motion data to the CSV file
• Reset the motion dictionary

You’ll also check that a motion["start_time"] value exists before running any of the other code. You only want to write to the CSV if a start_time timestamp was recorded:

def end_motion():
    if motion["start_time"]:
        led.off()
        buzzer.off()
        motion["end_time"] = datetime.now()
        write_to_csv()
        motion["start_time"] = None
        motion["end_time"] = None
    print("motion ended")

Add a call to .wait_for_no_motion() so that any initial motion is ignored:

print("Readying sensor...")
motion_sensor.wait_for_no_motion()
print("Sensor ready")

Set the .when_motion and .when_no_motion properties on the MotionSensor instance:

motion_sensor.when_motion = start_motion
motion_sensor.when_no_motion = end_motion

Finally, end the code with a call to pause() to keep the program running. The full Python code should look like this:

import csv
from pathlib import Path
from datetime import datetime
from gpiozero import LED, Buzzer, MotionSensor
from signal import pause

led = LED(14)
buzzer = Buzzer(15)
motion_sensor = MotionSensor(4)

output_csv_path = Path("detected_motion.csv")
motion = {
    "start_time": None,
    "end_time": None,
}

def write_to_csv():
    first_write = not output_csv_path.is_file()

    with open(output_csv_path, "a") as file:
        field_names = motion.keys()
        writer = csv.DictWriter(file, field_names)
        if first_write:
            writer.writeheader()
        writer.writerow(motion)

def start_motion():
    led.blink(0.5, 0.5)
    buzzer.beep(0.5, 0.5)
    motion["start_time"] = datetime.now()
    print("motion detected")

def end_motion():
    if motion["start_time"]:
        led.off()
        buzzer.off()
        motion["end_time"] = datetime.now()
        write_to_csv()
        motion["start_time"] = None
        motion["end_time"] = None
    print("motion ended")

print("Readying sensor...")
motion_sensor.wait_for_no_motion()
print("Sensor ready")

motion_sensor.when_motion = start_motion
motion_sensor.when_no_motion = end_motion

pause()

Save the file and run it to test out your new motion detector alarm:

pi@raspberrypi:~/python-projects $ python3 motion_detector.py
Readying sensor...
Sensor ready

Now if you wave your hand in front of the motion detector, then the buzzer should start beeping and the LED should flash. If you stop moving for a few seconds, then the alarm should stop. In the console you should see the following:

pi@raspberrypi:~/python-projects $ python3 motion_detector.py
Readying sensor...
Sensor ready
motion detected
motion ended
motion detected
motion ended
...

Go ahead and stop the program with Stop in Mu or Ctrl + C . Let’s check out the CSV file that was generated:

pi@raspberrypi:~/python-projects $ cat detected_motion.csv
start_time,end_time
2020-04-21 10:53:07.052609,2020-04-21 10:53:13.966061
2020-04-21 10:56:56.477952,2020-04-21 10:57:03.490855
2020-04-21 10:57:04.693970,2020-04-21 10:57:12.007095

As you can see, the timestamps for the motion’s start_time and end_time have been added to the CSV file.

Congratulations! You’ve created a non-trivial electronics project with Python on the Raspberry Pi.

Next Steps

You don’t have to stop here. There are many ways you could improve this project by leveraging the capabilities of Python on the Raspberry Pi.

Here are some ways to level up this project:

• Connect the Raspberry Pi Camera Module and have it take a photo whenever motion is detected.

• Connect a speaker to the Raspberry Pi and usePyGame to play a sound file to intimidate an intruder.

• Add a button to the circuit to allow a user to manually toggle motion detection on or off.

There are many ways to upgrade this project. Let us know what you come up with!