Add an OLED Stats Display to Raspberry Pi OS Bullseye

Raspberry Pi OS Bullseye has recently been released and with it comes a number of improvements, but most of them are under the hood. There aren’t that many visual differences, the most noticeable is probably the new default desktop background which is now a sunset over a dam or lake.

Raspberry Pi OS Bullseye

With this operating system upgrade, we’ve also got the usual bugs and software incompatibilities. These have caused my previous OLED stats display tutorial, that I used for my Raspberry Pi Desktop Case, to no longer work correctly. If you follow the previous tutorial, you’ll be presented with a host of errors.

Errors Running I2C OLED Stats Display

So in this tutorial, I’ll take you through the installation and setup process to get the same 128×64 I2C OLED display running on Raspberry Pi OS Bullseye.

Here’s the video tutorial, read on for the written steps and commands.

What You Need For This Tutorial

Connecting Your OLED Stats Display To Your Raspberry Pi

To start out, we’re going to go through the same process to connect the OLED stats display to our Raspberry Pi. To do this, you’ll need a 4 wire female to female jumper cable. The colours don’t matter, they’re just there to help you keep track of which wire goes to which terminal.

4 Wire Connector Cable and I2C OLED Display

The OLED display’s terminals are labelled on the front, which seems to confuse a lot of people since the pins extend out the back of the display.

128x64 I2C OLED Display Pinout

This is especially difficult to spot once the display has been installed into the case and the front area of the display is no longer visible. So make sure that you jot them down before installing the display into a case or holder.

Pin Labels Hidden By Case

The pin arrangement is most commonly GND, VCC, SCL and SDA. Don’t just copy this arrangement, make sure you check your own display as there are versions of these displays with the VCC and GND pins switched around. If you connect power to them incorrectly they’ll most likely be damaged and will no longer work, even if you correct the wiring afterwards.

Different VCC and GND Pinout On Display

Plug your ribbon cable into these four pins and then take note of which colour you’ve got connected to which pin. If you’re installing the display into your case before connecting it to your Raspberry Pi then it’s a good idea to write down which colour is connected to which pin so that you don’t forget.

Plug in the Ribbon Cable

Next we can plug the other ends of the jumpers into the Raspberry Pi’s GPIO pins. The Pi’s GPIO pinout diagram can be found quite easily online and is available from the official website.

Raspberry Pi 4 Pinout
Source: RaspberryPi.org

Make sure that your Pi is off and the power is disconnected before plugging or unplugging jumpers from the GPIO pins. You don’t want to short a connection or plug a lead into the incorrect pin by mistake and not have a chance to check your connections before powering it up.

Raspberry Pi GPIO Pins

You’ve got a few options for the GND and VCC jumpers. I usually plug the GND jumper into Pin 9 (you can use any pin labelled GND). And I plug the VCC jumper into Pin 1, which is a 3.3V power pin. These displays can operate on 3.3V or 5V inputs, so any power pins on the Pi’s GPIO header will work.

VCC and GND Connections To Raspberry Pi

Next, we need to connect the communication jumpers SCL and SDA, which just get plugged into the corresponding GPIO pins. Plug SCL into Pin 5 and SDA into Pin 3. Don’t get confused between the GPIO numbers and the Pin numbers, ignore the GPIO numbers on the diagram and just go by the SDA and SCL labels and the corresponding pin numbers.

SDA and SCL Connections To Raspberry Pi

Check all of your connections again and you’re then ready to power your Pi up and get started with programming the display.

Completed I2C OLED Display Connections

Programming The OLED Stats Display

Now that we’ve got the display connected, we can look at programming our Raspberry Pi to display the performance stats. I’m going to be doing this on a fresh install of Raspberry Pi OS Bullseye by using the Raspberry Pi Imager utility to flash the operating system image to a new microSD card.

Put the SD card into your Pi’s SD card slot and plug in your power adaptor. Once you’ve booted up your Pi, you should be on the Raspberry Pi OS desktop. It’s possible to do this installation on a headless Pi as well using the same steps.

Raspberry Pi OS Bullseye

Update Your Pi and Install The CircuitPython Library

Open up a new terminal window and start by making sure that your Pi’s software is all up to date by running the following commands:

sudo apt-get update
sudo apt-get full-upgrade
sudo reboot
sudo apt-get install python3-pip
sudo pip3 install --upgrade setuptools
Updating The Raspberry Pi

Next, we’re going to install the Adafruit CircuitPython library using the following commands:

cd ~
sudo pip3 install --upgrade adafruit-python-shell
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py
sudo python3 raspi-blinka.py

Hit yes to any prompts which may come up and yes (Y) to reboot at the end.

Installing The Adafruit Circuit Python Libraries

Check That Your Display Can Be Seen

This previous installation script should also have enabled I2C communication, which is needed to communicate with the display. You can check that it is enabled and your Pi is able to see the connected display by entering the following command:

sudo i2cdetect -y 1

You should then see a table, similar to the one shown below, which has a single set of characters in it (typically 3c for these displays). This code indicates the I2C address of your display.

Checking The I2C Display Address

If it hasn’t shown up then either I2C communication isn’t turned on, which can be done through the configuration utility, or your wiring is not correct. If you get a table full of characters (all addresses shown) then you’ve probably made a wiring mistake as this happens if SDA is shorted to ground. Go back and re-check your connections to your Pi and display and re-check that you’ve got I2C communication enabled after a reboot.

To enable I2C communication, use the configuration utility by entering:

sudo raspi-config

Don’t proceed with trying to get the script to work if you don’t get the correct response in this step. If your Raspberry Pi isn’t able to see the display that is connected to it then it won’t be able to communicate with it to get anything displayed.

Install The OLED Stats Display Script

Next, we need to install the CircuitPython libraries specific to the display. Start by entering the following commands:

pip3 install adafruit-circuitpython-ssd1306
sudo apt-get install python3-pil

Now we just need to download the actual script. Rather than trying to edit it on the Pi, I’ve made it available on Github in its completed form, so you just need to run the following line to copy it to your Pi:

git clone https://github.com/mklements/OLED_Stats.git
Installing The Stats Display Script

Navigate to the new cloned directly by entering:

cd OLED_Stats

Then run the script by entering:

python3 stats.py
I2C OLED Stats Display Running

Automating The Script To Run On Start-up

Now we’ve got the display running, but it’ll stop as soon as we close the terminal window and we’d like it to run automatically on startup. We’re going to do this using crontab.

Open up crontab by entering the following command:

crontab –e

If this is the first time you’re opening crontab then you’ll be prompted to select an editor, select 1 and hit enter.

Add the following line to the end of the file to run the script:

@reboot python3 /home/pi/stats.py &

Don’t forget the “&” at the end to tell the Pi to continue starting up and to run the script in the background.

Adding The Script To Crontab For Automatic Startup

We’ll also need to copy the stats.py script and font into the home directory. You can also just reference the correct path in the previous step, but I find that this is less reliable. If you do leave them in the downloaded directory, you’ll need to amend the crontab command to read:

@reboot cd /home/pi/OLED_Stats && python3 stats.py &

Make sure that you copy both the stats.py script and the PixelOperator font into the /home/pi directory.

Copy The Script To The Home Directory

Save the crontab file when you exit and then try rebooting your Pi to see if it is working correctly.

If you’ve followed the process correctly, you should now have a working OLED stats display that starts up automatically each time your Pi boots up. You can now go ahead and install it into your case if you haven’t done so already.

I2C Stats Display Running On Raspberry Pi OS Bullseye

Finish Off Your Pi Desktop Case Build

If you’re using an Ice Tower with your OLED stats display, plug the fan’s power cables into the 5V and GND GPIO pins next to the display’s connections as I’ve done.

Connecting The Ice Tower Fan To The GPIO Pins

Close up your case and your Raspberry Pi Desktop Case build is now complete.

Let me know how you find this tutorial in the comments section below. I’d love to hear your feedback and suggestions.

Stats Displays Running One Raspberry Pis
Michael Klements
Hi, my name is Michael and I started this blog in 2016 to share my DIY journey with you. I love tinkering with electronics, making, fixing, and building - I'm always looking for new projects and exciting DIY ideas. If you do too, grab a cup of coffee and settle in, I'm happy to have you here.

16 COMMENTS

  1. I am having issues to run the script

    python3 /home/pi/OLED_Stats/stats.py
    Traceback (most recent call last):
    File “/home/pi/OLED_Stats/stats.py”, line 41, in
    font = ImageFont.truetype(‘PixelOperator.ttf’, 16)
    File “/usr/lib/python3/dist-packages/PIL/ImageFont.py”, line 852, in truetype
    return freetype(font)
    File “/usr/lib/python3/dist-packages/PIL/ImageFont.py”, line 849, in freetype
    return FreeTypeFont(font, size, index, encoding, layout_engine)
    File “/usr/lib/python3/dist-packages/PIL/ImageFont.py”, line 209, in __init__
    self.font = core.getfont(
    OSError: cannot open resource

    If i try to run the script as follows it works
    [email protected]:~ $ cd OLED_Stats/
    [email protected]:~/OLED_Stats $ python3 stats.py

    • It looks like it isn’t seeing the font in the same directory (or isn’t looking in that directory for the font). Either use the default font or just put the script and font into the default directory.

  2. Hi Michael !
    Great job but BLINKA just only works in Raspberry PI OS, how can I install it in other Distro (ubuntu mate) ?

    I tried with your other videos but I could not get it

    • You’ll need to use a library for your distro that allows you to run an OLED display. Each distribution has different package requirements, so you won’t find a single solution to all.

  3. Michael, Thank you so much for this. As a complete newbie to Pi i spent several days trying to figure out what i was doing wrong. This updated guide now works perfectly. Only slight issue i had being a newbie, was trying to work out how to save the crontab file. you may want to add “press control X to save”.
    Many thanks.

  4. Hi, i read the article Mini Raspberry Pi Server With Built In UPS, and the script you supplied with UPS stats, does not work with this method of installation. I tried to make one my self, but i’m not so good at programming. Please can you make another script, working with this new method?

  5. Help please!
    I’m trying this on a R-Pi 3B but the display is showing almost all pixels On and some Off.
    On the top of the display it shows some “Disk” stuff.
    I’m using a 128×64 display and Raspberry Pi OS.
    All the wiring is correct.
    I even tried another display to check if the previous was faulty.

  6. getting this message when i try to run the script:

    [email protected]:~/OLED_Stats $ sudo python3 stats.py
    Traceback (most recent call last):
    File “/home/pi/OLED_Stats/stats.py”, line 6, in
    import board
    ModuleNotFoundError: No module named ‘board’

  7. If you leave the contents in the original folder and want to run the script on boot, nano into stats.py then locate
    “font = ImageFont.truetype(‘PixelOperator.ttf’, 16)”
    and change it to
    “font = ImageFont.truetype(‘/home/pi/OLED_Stats/PixelOperator.ttf’, 16)”
    or the full path to the folder you have it in. Save and then try again. Should fix you up

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Latest posts

Turning a Beelink SER 3 into a Custom Ryzen 7 Mini Gaming PC

Today we’re going to be taking a look at the new SER 3 series Mini PC from Beelink which has an AMD Ryzen 7...

Add an OLED Stats Display to Raspberry Pi OS Bullseye

Raspberry Pi OS Bullseye has recently been released and with it comes a number of improvements, but most of them are under the hood....

ClonerAlliance UHD Pro Video Capture Box Unboxing & Review

Today, we're going to be taking a look at the ClonerAlliance UHD Pro video capture box which was sent to me by the team...

Related posts