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.
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.
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
- Raspberry Pi 4 – Buy Here
- Ice Tower – Buy Here
- Micro SD Card – Buy Here
- Raspberry Pi Power Supply – Buy Here
- I2C 128×64 OLED Display – Buy Here
- 4 Wire Female to Female Jumper Cable – Buy Here
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.
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.
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.
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.
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.
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.
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.
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.
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.
Check all of your connections again and you’re then ready to power your Pi up and get started with programming the display.
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.
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 apt-get install python3-pip
sudo pip3 install --upgrade setuptools
Next, we’re going to install the Adafruit CircuitPython library using the following commands:
sudo pip3 install --upgrade adafruit-python-shell
sudo python3 raspi-blinka.py
Hit yes to any prompts which may come up and yes (Y) to reboot at the end.
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.
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:
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:
sudo 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
Navigate to the new cloned directly by entering:
Then run the script by entering:
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:
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.
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.
Make sure that you copy both the stats.py script and the PixelOperator font into the /home/pi directory.
cd OLED_Stats cp PixelOperator.ttf ~/PixelOperator.ttf cp stats.py ~/stats.py cp fontawesome-webfont.ttf ~/fontawesome-webfont.ttf
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 &
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.
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.
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.