Block I Illinois Library Illinois Open Publishing Network

Orange Unit: A Person-Centered Launch

4C: Getting Started with the Raspberry Pi

Setting up a Raspberry Pi 3, 4, or 400 for the first time depends considerably on what came with the purchase of that Raspberry Pi, what you have on hand, and the ways you plan to use your Raspberry Pi. It also depends on your skill level coming in and your interest, and availability for taking on the learning of new skills just to get things running. To facilitate demystifying technology for all, the following is based on a classroom context in which exercises are done using the Raspberry Pi operating system setup with a graphical user interface (GUI), given that it is the most widely used general purpose computer interface. First, set up a new Raspberry OS which will use a Raspberry Pi with direct connection to a monitor, keyboard, and mouse. At the same time, a given classroom cannot always provide a separate keyboard, mouse, and monitor for regular use with the Raspberry Pi. And as we move on in the book, we’ll be exploring ways a general-purpose computer can run software services, such as a web server used to collect, manage, and share data. These often run using a “headless” configuration in which regular work on the general-purpose computer only requires a source of power as primary management is done with either a remote command-line (CLI) or GUI interface. In introducing hardware and software server environments beyond personal computer models, ongoing use of the configured Raspberry Pi OS will allow for headless server operation and only require provision of power to the Raspberry Pi computer, and Internet connectivity of the Raspberry Pi. For most, it is also necessary to have a personal computers on the same Local Area Network as the Raspberry Pi, either physically or using a Virtual Private Network (VPN) system, such as the Cisco AnyConnect provided for the University network in which this textbook is being written. Finally, documentation of the IP address assigned to the Raspberry Pi computer will be needed, as we will not register the Raspberry Pi so that it is assigned a publicly accessible IP name. To connect to the Raspberry Pi OS in order to complete tasks, you will be able to choose between using a virtual network computer (VNC) graphical desktop system or a secure shell (SSH) command-line protocol connection. The Raspberry Pi project provides well documented instructions for getting started with a new Raspberry Pi computer and new Raspberry Pi OS.[1] This chapter and various other instructions throughout the book make use of key parts of text and images, both as is and remixed, of which you can find the originals on the Raspberry Pi company and the Raspberry Pi foundation websites.

The Raspberry Pi company and foundation license their material under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA) license. Regarding attribution, the Creative Commons notes that new authors have the following responsibility in using such licensed work: “You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.” Regarding share-alike: “If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.”

A Person-Centered Guide to Demystifying Technology stands by the Creative Commons and is itself licensed using the CC BY-SA license in support of lifelong learning, with special attention to those who are in marginalized and oppressed communities around the world. Indeed, one determinant in the selection of the Raspberry Pi computer and the Raspberry Pi OS instead of competing microcomputers and Linux operating system distributions was the Raspberry Pi project’s commitment to open publishing of all their educational materials under this Creative Commons license.

Choosing Your Path Forward

As noted above, the first setup of a Raspberry Pi can vary depending on what you have on hand. Here’s the list of physical materials used to write the following instructions in spring 2023:

Beyond the hardware, all exercises in this book have been tested using the Raspberry Pi OS port of Debian 11 Bullseye released by the Raspberry Pi project April 4, 2022. The focus of this release of the Raspberry Pi OS was on improved security, including a new, non-optional “Welcome to the Raspberry Pi Desktop” wizard that comes up on first boot of a new OS install. This requires the setup of a username and password prior, which is required upon login to the Raspberry Pi OS Desktop. There is a slight security risk of continuing to use the username “pi.” However, there are some applications, including those written for this book, that still make use of the /home/pi directory. To balance this, it is highly recommended you use a secure password. The April 2022 release also addressed a long-standing issue in which you needed a USB mouse and/or keyboard to initially pair Bluetooth peripherals such as a Bluetooth keyboard and mouse. The wizard now provides a prompt that can be used to pair with a Bluetooth device which has been put into pairing mode. In the Raspberry Pi Imager, this release provides a new set of steps within advanced options to allow “headless” use—no keyboard, mouse, or monitor needed, with all work being done through a remote connection—of the Raspberry Pi from the start. However, this pathway for setting up headless use of the Raspberry Pi does not work with the Virtual Network Computing (VNC) package we’ll be using, so this new feature will not be used.

The remainder of this chapter is broken down into three main processes:

  1. Exercise: Installing a Protective Case
    • Done once with a new Raspberry Pi 3 or 4 computer
    • Not needed for Raspberry Pi 400 computer
  2. Exercise: Installing the Raspberry Pi OS
    • Done for each new Raspberry Pi OS installation
    • Not needed if your microSD card came preinstalled with the Raspberry Pi OS
    • This can be done: on a new blank microSD card; to reinstall the same operating system for Raspberry Pi use; or to install a different operating system available for the Raspberry Pi
  3. Exercise: Setting Up a New Raspberry Pi OS
    • General configuration of the OS with things such as a username and password, Internet access, and updates
    • Raspberry Pi configurations for more specific use such as display and interface systems
  4. Exercise: Adding an Adafruit PiOLED Text Display
    • Done following each new Raspberry Pi OS configuration
    • If IP address assigned to the Raspberry Pi remains constant, the PiOLED may not be needed

Exercise: Installing a Protective Case

Look at your laptops, phones, TV’s, routers, and most other computer systems, and you won’t actually see the computer, but rather a protective case in which the computer is located. This is also the case for the new Raspberry Pi 400 Desktop. For those using a Raspberry Pi 3 or 4, a minimal protective acrylic case gives us the opportunity to see the Raspberry Pi computer directly and get the labeling of the General Purpose Input Output (GPIO) pins while also keeping the Pi secure.A picture of the protective acrylic case selected for use with the Raspberry Pi Model 3 and Model 4 computers used in my classes. This minimalist case includes basic labeling of the General Purpose Input Output, or GPIO) pins.

Looking at the image above, unseen is an acrylic pad on which the Raspberry Pi sits. It is held in place by two short and two long black screws that come with the package. On top of the Raspberry Pi, you’ll see a slightly shorter acrylic pad with GPIO labels facing the associated GPIO pins. It is held in place with the two taller black screws and provides protection to the top of the printed circuit board, integrated circuits, and connector slots.


You are ready to attach the Raspberry Pi to its new case.

  1. The bottom of the case has a dip on one of the shorter sides to provide room to insert a microSD card into the Raspberry Pi moving forward. Holding this at the top, insert the two longer black screws into the left holes, and the two shorter black screws into the right holes.
  2. Attach these screws to the acrylic using four black nuts. These only need to be hand tightened.
  3. Insert the four screws into these pins so that the microSD slot aligns with the dip in the acrylic.
  4. Attach nuts to the two shorter black screws above and below the GPIO pins.
  5. Place a white plastic tube to each of the two longer black screws.
  6. Lower the top acrylic cover to the tall back screws so that it sits on top of the white plastic tubes.
  7. Attach nuts to the two taller back screws to hold down the top of the acrylic case. These only need to be hand-tightened.

Key Takeaways

A case is used to protect electronics from wear and tear. They come in many shapes and forms. The design of the case impacts effective use in significant ways. To demystify technology, I’ve chosen to use an acrylic case with label identifying the GPIO pins as commonly used. But my choice of this particular Adafruit Pi Protector for Raspberry Pi was inspired through Limor Fried, whose goal in starting Adafruit in 2005 “was to create the best place online for learning electronics and making the best designed products for makers of all ages and skill levels.”[2] And it is further aligned with the Raspberry Pi project’s motivation of “Democratising technology—providing access to tools“—which in working to lower the barriers to entry by providing both a lower cost computer and extensive educational materials, is finding “Raspberry Pi computers being used everywhere from interactive museum exhibits and schools to national postal sorting offices and government call centres. Kitchen table businesses all over the world have been able to scale and find success in a way that just wasn’t possible in a world where integrating technology meant spending large sums on laptops and PCs,”[3]

A case is a social as much and more as a technical tool. It is a sociotechnical artifact that can provide you with insights into the designers, producers, and distributors of that product. Take a minute to look at the many sociotechnical cases you use in your daily life. What might be some of the motivations for each of their designs? What in these designs would you have done differently to help them work better for you? What in these designs has helped you work better than those of other devices you considered purchasing?

Exercise: Raspberry Pi OS Installation on a microSD Card

Sometimes you can find microSD cards with the Raspberry Pi OS with Desktop already installed, in which case you can jump straight to Exercise: First Boot of the Raspberry Pi OS.

But for most, an affordable option has been to purchase a fresh 16 GB or larger microSD. It’s recommended you select a microSD card whose speed categorization is the new A (for “application”) class. You’ll see an A1 logo next to the overall speed class, a number found within the C symbol. While the overall speed found with the C symbol determines the minimum write speed of the microSD, the application class goes on to determine how many read and write operations need to be completed within one second. For example, an A1 category, class 10 speed microSD card, will have a minimum write speed of 10MB/s (the class 10 speed requirement) that will also support at least 1500 read operations and 500 write operations per second (the class A1 speed requirement). All official Raspberry Pi microSD cards meet this specification.

The Raspberry Pi Foundation has developed a graphical SD card writing tool called Raspberry Pi Imager, which they suggest as the easiest option for most users, since it will download the image automatically and install it to the SD card a computer with an SD card reader. It works on Mac OS, Windows, and Ubuntu 18.04 and above. There are many USB-based SD card readers available, which you can then use if your computer does not come with its own SD card reader.

To set up and use Raspberry Pi Imager on your personal computer:

  1. Download the latest version of Raspberry Pi Imager, and install it to your personal computer.
  2. Insert a microSD card to your computer in the microSD slot, or connect a USB-based SD card reader with the microSD card attached into an available USB port.
  3. Open Raspberry Pi Imager.
    • For “Choose Operating System,” select the Raspberry Pi OS (32-bit) from the list presented, as this is the recommended operating system for most users.
    • For “Choose Storage,” select the USB mass-storage device you just added.
      • Make sure it matches the size of storage you expected. In my case, it lists 15.5 GB for my 16-gigabyte microSD card.
      • In case you’re not certain, you can remove the microSD card you plan to use, and it should disappear from the display.
  4. Review your selections and click on the Write button to begin writing data to the SD Card.
    NOTE: If using Raspberry Pi Imager on Windows 10 with controlled folder access enabled, you will need to explicitly allow Raspberry Pi Imager permission to write the SD card. If this is not done, the imaging process will fail with a “failed to write” error.
    Raspberry Pi Imager at the start of writing the OS to a microSD
  5. After the Raspberry Pi completes the writing of the image to the microSD, it will do a verification that everything was written successfully before providing a “Write Successful” popup. Click “Continue,” and then, if it wasn’t done automatically by the Imager, eject the new “USB Drive”[4] before removing the microSD.
    Raspberry Pi Imager pop-up window indicating "Write Successful" with details of which OS was written and the USB device to which it was written. A "Continue" button is provided at the bottom.
    For more, check out their brief introduction of the Raspberry Pi Imager in their 45-second video:

Exercise: First Boot of the Raspberry Pi OS

Once you have a microSD card with the Raspberry Pi OS installed, the next step is to do an initial configuration of the operating system. The following instructions were tested using Raspbian GNU/Linux 11 (bullseye).

  1. Connect your Raspberry Pi to a keyboard, mouse, and monitor. Check on the specifications of your Raspberry Pi hardware model, as port types and included components vary.
  2. Install the microSD card into the microSD port on the Raspberry Pi.
  3. Insert power to the Raspberry Pi.
    • For every newly installed Raspberry Pi OS, the first boot will go through a couple of passes to do some initial configurations:
      • By default, the first boot will be used to resize the microSD to make use of all available space.
      • A reboot will then take a few moments to do some further initial automated configurations before arriving at a “Welcome to the Raspberry Pi Desktop” message.
    Screenshot of the Raspberry Pi OS "Welcome to the Raspberry Pi Desktop" message as displayed in a monitor

    FAILING FORWARD TIPS: Essential Troubleshooting When You Have a Blank Screen on Your Monitor

    There are occasions when there is no display seen on the monitor even though it works for other HDMI devices such as your laptop. While this has become much less frequent over the years, it still occurs on occasion. Here are a few troubleshooting tips:

    1. Is the microSD card working?
      • With the keyboard, mouse, and monitor connected and with a microSD car installed, provide power to the Raspberry Pi.
      • The red LED found near the power port on the Raspberry Pi will come on, indicating that power is provided.
        • If this does not come on, try disconnecting and reconnecting power at the power port or from the power outlet.
        • Try using another power cable or power outlet.
      • The green LED found next to the red LED should begin blinking. It does so anytime the microSD card is written to or read from.
      • When booting the Raspberry Pi OS (32-bit), there will be many read/write activities, so the green LED will blink for a number of seconds. If it only blinks briefly and stops, test for problems that may be occurring here:
        • Is the microSD card fully installed?
          • Disconnect power from the Raspberry Pi.
          • Try disconnecting and reconnecting the microSD card.
          • Reapply power.
        • Is the Raspberry Pi OS properly installed?
        • Was some of the data on the microSD card destroyed?
    2. Is there a problem with the monitor or with the connection between the Raspberry Pi and the monitor?
      • Try connecting the Raspberry Pi to a different monitor.
        • Consider using the working monitor with the Raspberry Pi when one is needed. (We’ll be working to set up the Raspberry Pi to work without a keyboard, mouse, and monitor in an upcoming step below.)
      • Try using the same HDMI cable to connect another device to the same monitor.
        • If the Raspberry Pi does not work with either of the above, the problem may be related to the type of monitor being used.
        • Like other general-purpose computers in common use today, the Raspberry Pi OS is highly flexible with regard to monitor, as long as it provides an HDMI port.
        • There are times, however, when the Raspberry Pi does not accurately evaluate the screen format or supported resolutions of the monitor.
        • As mentioned in Orange Unit 3B: Computer Building Blocks, the Raspberry Pi uses a text configuration file called config.txt to do system-level hardware and software configurations that would have otherwise been done within a Boot Loader such as BIOS or UEFI.
        • It is possible to edit the config.txt file using computers running OS X or Windows, and all Linux-based computers.
          • Connect the microSD card to the computer.
          • Locate the new drive that appears (probably named Boot or something similar; on Windows this will also come with a new D:, E:, or other drive letter).
          • Use TextEdit (OS X), Notepad (Windows), or Mousepad (Linux) to open config.txt.
            • You may need to do this with administrative privileges, depending on the security configuration of your computer.
        • Consulting the Raspberry Pi documentation for video option in config.txt:
          • Uncomment the safe mode for HDMI by removing the # symbol in front of hdmi_safe=1.
        • Save the changes.
        • Eject the microSD card, and then remove it from the computer.
        • If your monitor works in safe mode:
          • Click on the Raspberry icon at the upper left, and then select Preferences -> Screen Configuration.
          • Click on Layout->Screens->HDMI-1->Resolutions, and select the best resolution for your monitor.
            • This sets the hdmi_mode post-bootup and replaces the one established via config.txt, which is used as a starting default.
          • Click Apply to test the selected resolution, hitting Cancel or OK to either try another setting or keep the selected setting.
          • Once you have the preferred resolution and other configuration options such as Frequency and Orientation, close Screen Configuration.
          • Reboot the Raspberry Pi.
          • If this seems to work well, open a terminal window and enter
            sudo mousepad /boot/config.txt.
          • Add back the # symbol in front of hdmi_safe=1 to again comment out this configuration option.
          • Save the changes, exit mousepad, and reboot the Raspberry Pi.
          • If the monitor now works properly, proceed to “First set up” below.

    There are additional configuration options within config.txt you might consult if you need to troubleshoot monitor displays of your Raspberry Pi further.[5]

  4. First set up:
    • Set Country—The instructions in this book were primarily tested within the United States using American English, but two-thirds of the readers of the first edition have come from the Asian and African continents. Ideally you can configure the Set Country components to match yours.
    • Create User—While it is extremely important to carefully create a highly secure password for your personal and professional devices, when working in a collaborative environment using a prototyping and educational system such as the Raspberry Pi, you may find it helpful to have a shared password in this specific context. But if this is done, be very careful to never put any data or information on the Raspberry Pi that you aren’t willing to have go public across the Internet!
    • Set Up Screen—Enable and again disable the “Reduce the size of the desktop on this screen” option to see if parts of the image are being missed because they don’t match the monitor display you are using.
    • Select WiFi Network—We plan to make ongoing use of a remote computing application like Virtual Network Computing (VNC) or secure shell (SSH). In almost all cases, for security by default this requires that the Raspberry Pi be on the same local area network (LAN) as the remote computer. If possible, select the WiFi network from the list that matches that being used by your personal computer.
      • NOTE: In some educational and work contexts, security may prevent an unrecognized computer from connecting to that network. Consult with your support team at your location on pathways forward if you find this to be the case.
      • As an example, at the University of Illinois Urbana-Champaign, there is an option to register devices other than personal laptops and mobile phones using a Wireless Guest and Device Management Portal. Whether a smart TV, video game console, or a Raspberry Pi, a student can register their personal devices using this Portal by identifying the media access control (MAC) address associated with the wireless Ethernet network interface card (NIC). Additionally, departmental accounts can register Raspberry Pi’s, Arduino’s, and Internet of Things devices being used for their studio courses. Either way, a personal computer on the IllinoisNet Wi-Fi network is able to remotely access these other devices on the IllinoisNet_Guest Wi-Fi network.
    • Update Software—If you can connect the Raspberry Pi to a WiFi network, it will now do any needed updates in the operating system and installed applications. If possible, click Next to do this now, as this will be needed for future exercises.
      • Selecting Skip may be necessary for those with limited time or Internet access now, in which case updates will need to be done later.
      • If you get a popup stating the process reached a timeout, this also indicates an Internet access problem, in which case updates will need to be done later.
    • With setup complete, you’ll be prompted to press Restart.
      • After restarting, you may see an update prompt to the left of the Bluetooth and Wi-Fi icons. Make sure you’re connected to Wi-Fi, and then click on the icon and select to either start the install or to first view the available updates before starting the install.
        Screenshot of the Raspberry Pi OS desktop. The mouse pointer is hovering over the updates available icon at the upper right and a pop up stating updates are available. The update window is displayed on the desktop as the icon has been clicked.
  5. Raspberry Pi Configuration—While the Raspberry Pi OS took you through some general configurations upon first boot of a newly installed microSD, there are a range of other configurations that will be needed at some point. Let’s do some of these next:
    • Click on the Raspberry icon in the upper left, and then, in the drop-down menu, go to Preferences and select Raspberry P Configuration.
      Launching Raspberry Pi Configuration
    • The Raspberry Pi Configuration has several tabs in which you can configure different core parts of the operating system. At a minimum, make the following configuration changes:
      • System
        • Password—If you didn’t set one previously, now’s the time to do that.
        • Disable the Splash Screen. Moving forward during the boot process, you’ll see a line-by-line list of actions being taken, along with indications of success or failure. A Splash Screen is now widely used by different operating systems to hide many of these to facilitate a more inviting initial experience upon starting a computer.
      • Display
        • Headless Resolution: I recommend setting this to 1280×720 to assure a reasonably usable display of the Raspberry Pi desktop, but one that is still smaller than that of the computer you will be using to remotely access your Raspberry Pi moving forward.
      • Interfaces. Make sure each of the following are enabled:
        • SSH—the secure shell server for remote command line access to your Raspberry Pi. Enabling SSH means that the server is restarted each time you boot the Raspberry Pi.
        • VNC—the Real VNC server for remote Virtual Network Computing access. Enabling VNC means that the server is restarted each time you boot the Raspberry Pi.
        • SPI—the Serial Peripheral Interface on the GPIO header. Enabling here also automatically loads the SPI kernel module needed for various products using this serial interface.
        • I2C—the Inter-Integrated-Circuit bus on the GPIO header. Enabling here also automatically loads the I2C kernel module.
          Unlike UART and SPI, which provide send and receive communications to one or two attached devices, respectively, I2C is a bus and can work with device addressing to do serial send and receive communications with many more devices.
        • Serial Port—the GPIO transmit (GPIO #14) and receive (GPIO #15) pins on the Raspberry Pi can provide Universal Asynchronous Receive Transmit (UART) communication with a remote device, using something like a TTL to USB serial cable between GPIO #14 and GPIO #15 and the USB port on a computer.
        • Serial Console—provides a serial console display to a remote device using serial communication.
      • Localisation—Here’s where you can set up Locale, Timezone, Keyboard, and WiFi Country if you didn’t do this during the “Welcome” setup above, or if you need to make changes at any point.
    • Once you’ve completed configuration setup, click OK. You’ll be prompted to reboot for the changes to take effect. You may see a few reboots occur for everything to fully take effect.
  6. Once complete, you’ll return to the Raspberry Pi OS desktop, where you’ll now see an additional Real VNC server icon at the top:
    Raspberry Pi VNC menu icon
    • Click on the VNC tab to identify the IP address(es) assigned to your Raspberry Pi under “Connectivity.” You’ll use this IP address to access your Raspberry Pi remotely using a VNC client on your personal computer.
      Screenshot of the VNC Server Window as seen on the Raspberry Pi OS desktop where you can identify the IP addresses and other helpful information.
    • On your computer, open a new tab in your web browser. In the address bar, type in Download and install RealVNC Viewer on your computer.
    • Open RealVNC Viewer on your computer. As with a web browser, you’ll find an address bar where it says, “Enter a VNC Server address.” Type in the IP address of the Raspberry Pi you just identified.
      • If prompted regarding VNC Server Identity Check Failed, click “Continue” as you can confirm you are connecting to the expected Raspberry Pi VNC Server.
      • When prompted, use the username and password you just configured for your Raspberry Pi OS. You can save this in VNC Viewer for automatic logins in the future.
    • The VNC icon in the Raspberry Pi OS menu will change from blue on white to blue on black, as viewed from both the Raspberry Pi monitor and your VNC Viewer remote display of the Raspberry Pi OS desktop.
      Raspberry Pi OS Desktop as seen in VNC Viewer
      • Moving the Raspberry Pi mouse will be seen in the VNC viewer display, and clicking on the VNC Viewer display and then moving your computer mouse will be seen on the Raspberry Pi monitor!
      • As with past exercises, this may prove to “not-yet” be working, requiring strategic “fail-forward” troubleshooting.
    • From here, as long as you know the IP address of a Raspberry Pi, you will no longer need a keyboard, mouse, and monitor for your Raspberry Pi, and will be able to instead manage things remotely from your computer. The Raspberry Pi can now be run “headless.”
      When you connect to a new Raspberry Pi, you may need a mouse, keyboard, and monitor to identify the IP address of the new Raspberry Pi before returning to headless operation. If your Raspberry Pi is provided a dynamic IP address, the address assigned may change at any moment, in which case you may need the keyboard, mouse, and monitor temporarily. Therefore, in the next exercise, we’ll setup an organic LED (OLED), on which the IP address can be listed for continuous headless operation.
      NOTE: You may be able to connect from a desktop or laptop web browser to the gateway router for your local area network (look around the case of the router to find its default IP address, and enter that into the URL address bar of the browser). In the router’s website, there is often a listing of connected devices and the IP addresses they have been assigned.
      NOTE: On occasion, I have found that the Headless Resolution setup above will somehow conflict with the RealVNC Viewer program on your personal computer. It has not occurred frequently enough for me to fully diagnose a cause. And in most cases, rebooting the Raspberry Pi has been sufficient to overcome this problem. Only once did I need to reconnect the Raspberry Pi to a keyboard, mouse, and monitor to again run Raspberry Pi Configuration to adjust the Headless Resolution under Display.

Try Something New!

Instead of working remotely using the VNC GUI, it’s possible to open a terminal window on your laptop to use Secure Shell to login remotely. On your computer’s terminal, type:

ssh pi@x.x.x.x

where x.x.x.x is the IP Address of your Raspberry Pi.

After logging in using SSH, you can run any terminal-based applications. Many that have a GUI version, such as Raspberry Pi Configuration, also have a CLI version. For configuration, you would instead type the following in the SSH terminal window:

sudo raspi-config

Key Takeaways

In this exercise, we launched the Raspberry Pi microcomputer with the Raspberry Pi OS for the first time. For anyone who has used a brand-new computing device (e.g., computer, tablet, mobile phone) for the first time, you’ll have likely found a range of similarities and differences. These similarities and differences, though, aren’t just between the Raspberry Pi and that of all the other computers you’ve ever used. Rather, brands and generations of computers each have been shaped by a wide range of social, cultural, and economic factors that have influenced the look, feel, and functionality of a given device within a given context. To this extent, Raspberry Pi is just like other computers in use today.

  • Compare and contrast your experiences with the different computers you have used. There are three primary types of operating systems used today:
    • Microsoft Windows-based operating systems developed by Microsoft in the early 1980s.
    • Apple Mac-based operating systems, a Unix-based system released at the end of the century to replace the “classic” Mac OS introduced in 1984.
    • Linux-based operating systems, including:
      • Android, a mobile operating system developed by Google, first commercially used in 2007.
      • Chrome OS, an operating system that uses the Google Chrome web browser as its principal user interface, first used commercially in 2011.
      • Ubuntu (first released in 2004) and other popular Linux distributions used on laptop, desktop, and server computers around the world.
      • Raspberry Pi OS with Desktop, which we just set up for the first time.
    • If possible, compare and contrast any brand-new computers you’ve turned on for the very first time.
    • As you compare operating systems, consider how the following components vary:
      • The command line interface
      • The setup and configuration files
      • The included everyday applications

Exercise: Adding an Adafruit PiOLED Text Display

An organic light-emitting diode (OLED) is one or more LEDs in which an organic compound is added on top to emit light in response to an electric current. The OLED in the image below provides 128 individual white LEDs on the x-axis and 32 individual white LEDs on the y-axis, for a total of 4,096 white LEDs. In addition to these white LEDs, the printed circuit board of this display also has a single-chip driver and controller, designation SSD1306. It is through the SSD1306 chip that data and commands are exchanged between the OLED dot-matrix graphic display system and the device to which it is connected using the I2C serial communication bus—in our case, pins 2 and 3 on the Raspberry Pi GPIO.

Adafruit includes software drivers for use on the device in their Python library, which will allow us to keep track of the IP address, operating system, CPU load, and disk usage of the Raspberry Pi. The following steps will need to be done once for each newly installed operating system—specialty drivers generally are not installed within the base of a general-purpose operating system such as the Raspberry OS, Microsoft Windows, Mac OS, etc.

If the GPIO pins on your Raspberry Pi are readily accessible, you can connect the PiOLED to the following GPIO pins (use the table to match the image below with the associated Raspberry Pi GPIO, or General Purpose Input Output, pins being used):

3.3V #2 #3
Raspberry Pi with working PiOLED text display. The Adafruit flower icon at the upper left of the PiOLED points to the hole that is connected to the 5-volt pin on the GPIO.


  1. Open a terminal window on the Raspberry Pi. Type in the following to install the needed Python 3 libraries and drivers:
    sudo pip3 install adafruit-circuitpython-ssd1306
    • If you get an error that pip is not installed, you will need to rerun the above after first typing in the following:
      sudo apt install python3-pip
      sudo apt install python3-pil
    • If this still doesn’t work, you may need to do a full update of the Raspberry Pi OS and installed applications by typing in the following before rerunning the above:
      sudo apt update
      sudo apt full-upgrade
  2. Next, type the following in the terminal window to create new directories in your home directory.
    mkdir Code
    mkdir Code/Python
    cd Code/Python

    Creating Code and Python folders
  3. On the Raspberry Pi, click the blue circle icon associated with the Chromium web browser. Then enter the following URL:
  4. Skim through the Python code to get a rough sense of what it’s doing, and then download the code to your Raspberry Pi.
    • It may state that “Your Download is In Progress” while also asking if you want to “Sign Up” or “Log In.” This popup can just be closed—no account or log in is required.
    • You’ll likely receive a prompt stating, “This type of file can harm your computer. Do you want to keep anyway?”
      • As Python files can include malicious code, this is a safety mechanism to ensure that you trust this program.
      • Select Keep here.
    • Click on the Carat ( ̂) symbol where it lists the downloaded file. From the popup, select “Show in folder” to open the Folders Application.
  5. In the left section of the Folders window, click on the right-angled triangle in front of the Code directory to expand the subdirectories within Code. This will let you view the Code/Python subdirectory.
    • Drag the code from /home/pi/Downloads into the /home/pi/Code/Python subdirectory.
      Moving from folder Downloads to folder Code/Python
    • Click on the Python subdirectory to again view in the right section of Folders.
    • Right-click to receive a drop-down menu of options.
      Right click on the to get a dropdown menu of options
  6. From here, select Thonny Python IDE, a relatively beginner-friendly Python Integrated Development Environment (IDE) that comes with Raspberry OS Desktop.
  7. In Thonny, click on the Run icon.
    • If everything goes well, you should see an indication at the bottom of Thonny that everything is OK.
    • And on the PiOLED, you should now see the IP Address of your Raspberry Pi.
    • In the following images, note that the VNC Viewer and the program being displayed using the PiOLED both indicate the same Raspberry Pi IP address, After reviewing these images and associated text, proceed to the next step to have run automatically each time the Raspberry Pi is booted.
      Screenshot with the Thonny run icon highlighted. Click this to run
      Working PiOLED on Raspberry Pi 3
      Below is an image of a Raspberry Pi 3 side by side with a Raspberry Pi 400, on which the PiOLED is also set up. By default, the GPIO pins of the Raspberry Pi 400 are on the backside of the keyboard. In the image, an Adafruit CYBERDECK HAT is used to provide the same GPIO pin layout in a forward-facing location. And an Adafruit GPIO Reference Card for Raspberry Pi has been placed on top of the CYBERDECK to provide labeling similar to that provided by the Adafruit Pi Protector for Raspberry Pi installed during the first exercise of this chapter.
      Working PiOLED on Raspberry Pi 400
      Note that both the Raspberry Pi 3 and Raspberry Pi 400 are on the same 172.16 local area network, and a remote computer’s VNC Viewer can make connections to both simultaneously.
      Raspberry Pi 3 and 400 VNC Viewer displays side-by-side
  8. With the program tested, let’s set it up to automatically run every time the Raspberry Pi boots up.
    • In the Raspberry Pi terminal window, type:
      sudo mousepad /etc/rc.local
    • Scroll to the bottom of the rc.local file you now have opened in Mousepad. In a new line just above the command “exit,” type:
      sudo python3 /home/pi/Code/Python/ &
      Screenshot of the mousepad editor with the line "sudo python3 /home/pi/Code/Python/ &" added at the bottom of the /etc/rc.local file
    • Click on the File option in Mousepad to save the edited file, and then close Mousepad.
    • In the terminal window, type:
      sudo reboot now

Watch the newly installed PiOLED and the newly configured RealVNC viewer. Together, you should see that the Raspberry Pi goes through a full reboot process, and that the PiOLED automatically restarts and provides a continuous update of baseline information regarding the Pi. At this point, you should be provided with any new IP Address the Raspberry Pi is assigned if it is used in different locations in which it is set up to connect on the Local Area Network (LAN).

Wrap Up

In these exercises, we’ve worked to: 1) do a one-time installation of a case on the Raspberry Pi computer; 2) install the Raspberry Pi OS Desktop to a microSD card and do an initial configuration of this operating system for ongoing remote management; and 3) add drivers and Python code to the Raspberry Pi OS so that when attached, a 123×32 PiOLED mini-display can be used to determine the current IP address, operating system, CPU load, and disk usage of the Raspberry Pi.

As was noted in Orange Unit 3B: Computer Building Blocks, the operating system is installed and maintained on a storage device like a hard drive or microSD card. But even the newest versions of SSD and microSD storage devices are like our old paperwork that we store up in an attic. We can’t do anything with it beyond just storing it there. When a computer is turned on, those instruction sets in the operating system which are immediately needed are moved out of storage and into random access memory (RAM). We sometimes call this “booting” a computer, also called “boot up” or “start up.” We disabled the splash screen to watch the line-by-line work done to boot a computer.

  1. For those interested, the Raspberry Pi Start Up instructions include a section on how to do this “headless.”
  4. In the file viewer for your operating system, click on the eject icon, or right-click on the filename of the microSD and select eject.
  5. If the monitor works during initial boot with a console display, but remains blank when it switches to the graphical user interface (GUI), you may need to conduct some additional tests in config.txt. It is recommended that you remove or add comments one line at a time, returning the changed line to its previous setting before testing a new configuration line. After trying several one at a time, you can then move to testing in combinations. Some configuration lines that may prove helpful include:
    • config_hdmi_boost Configures the signal strength of the HDMI interface.
      • The minimum value is 0, and the maximum is 11.
      • The default for current versions of the Raspberry Pi is 5. It is set to 4 in hdmi_safe mode.
    • hdmi_group The hdmi_group command defines the HDMI output group to be either CEA (Consumer Electronics Association, the standard typically used by TVs) or DMT (Display Monitor Timings, the standard typically used by monitors). This setting should be used in conjunction with hdmi_mode.
    • hdmi_mode Together with hdmi_grouphdmi_mode defines the HDMI output format. Format mode numbers are derived from the CTA specification. To set a custom display mode not listed here, see more information on the forums. Look through the lists to determine a good working mode for your monitor.
    • hdmi_force_mode Setting to 1 will remove all other modes except the ones specified by hdmi_mode and hdmi_group from the internal list, meaning that they will not appear in any enumerated lists of modes. This option may help if a display seems to be ignoring the hdmi_mode and hdmi_group settings.
    • hdmi_force_hotplug Setting hdmi_force_hotplug to 1 pretends that the HDMI hot plug signal is asserted, so it appears that a HDMI display is attached. In other words, HDMI output mode will be used, even if no HDMI monitor is detected.


Icon for the Creative Commons Attribution-ShareAlike 4.0 International License

A Person-Centered Guide to Demystifying Technology, 2nd Edition Copyright © 2023 by Martin Wolske Copyright © 2023. Copyright “Ideating and Iterating Code: Scratch Example” © 2020 Betty Bayer and Stephanie Shallcross. Copyright “Introducing the Unix Command Line” © 2020 Martin Wolske, Dinesh Rathi, Henry Grob, and Vandana Singh. Copyright “Security and Privacy” © 2020 Sara Rasmussen. Copyright “Storytelling in the Information Sciences” © 2023 Yingying Han and Martin Wolske. This book is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License, except where otherwise noted.

Share This Book