Connect and Program An OLED Stats Display For Your Raspberry Pi

In this guide, I’ll show you how to program a 128×64 I2C OLED stats display as a quick dashboard for your Raspberry Pi. I use this script on my Raspberry Pi Desktop Case and a lot of people have asked me for some more in-depth setup and programming instructions to get it running.

You can make your own Raspberry Pi Desktop case by following my build guide, or buy a premade kit from my Etsy store.

This guide is written specifically for a Raspberry Pi 4B running Raspberry Pi OS, although you should be able to work through it for other Raspberry Pi models.

Raspberry Pi Desktop Case

Here’s a video guide to connect and program the OLED stats display, read on for the full written guide and script modifications.

What You Need For This Project

Amazon Affiliate Links

Banggood Affiliate Links

Connecting Your I2C OLED Stats Display To Your Raspberry Pi

We’ll start by hooking the display up to the Raspberry Pi. To do this, you’ll need a 4 wire female to female jumper cable. The colours on the cable don’t matter, they’re just there to help you keep track of which wire goes to which terminal.

I2C OLED Display and Ribbon Cable

The OLED display’s pins are labeled on the front, which seems to confuse a lot of people, especially when they’ve installed the display into a case or housing and the front area above the screen is no longer visible.

I2C OLED Display Front and Pin Labels

These are most commonly GND, VCC, SCL, and SDA. Don’t just copy this arrangement though, make sure you check your own display as there are versions of this display that have the VCC and GND pins the other way around.

OLED Display Pinout

These displays don’t have reverse polarity protection, so if you connect them incorrectly (even just once) then it’s quite likely that they’ll be damaged and will no longer work, even if you correct the wiring afterward.

I2C OLED Display Rear

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

Plug Ribbon Cable Into Display

Next, you need to plug the other ends of the jumpers into your Raspberry Pi’s GPIO pins. The Pi’s GPIO pinout diagram can be found quite easily online and is available on the official Raspberry Pi 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 connection before powering it up.

You’ve got a few options for the GND and VCC jumpers. I usually plug the GND jumper (mine is green) into Pin 14, but you can use any pin labelled Ground. I plug the VCC jumper (mine is blue) into Pin 1, which is a 3.3V power pin. Again, you can use any of the 3.3V or 5V power pins as this display can run on both 3.3V and 5V.

Connect Power Cables 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 (mine is purple) into Pin 5 and SDA (mine is white) 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.

Connect Communication Cables To Pi

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

Connections Between Pi and OLED Display

Programming The OLED Stats Display

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, it’s just easier to make the required layout changes to the script in the full version first.

Enabling & Testing I2C Communication

To get the display to show our Raspberry Pi’s performance stats, we’re going to be running a Python script. Before we do this we need to enable I2C communication on the Pi as this is how it communicates with the display. You can either do this through the preferences menu or by typing this command into a new terminal window:

sudo raspi-config
Enable I2C Communication

Select interfacing options, then I2C and then select Yes and then reboot the Pi by typing in the following command:

sudo reboot

Once your Pi has rebooted, you need to check that the following 3 libraries have been installed. You may already have them installed, but it’s worth checking. Run each one of these commands individually in your terminal:

sudo apt-get install python-smbus
sudo apt-get install i2c-tools
sudo pip3 install Adafruit_BBIO
Install The Required Libraries

Once you’ve done that then you can check that your Pi is able to see that your display is connected. You can do this by typing in the following command:

sudo i2cdetect -y 1

You should then see a table, similar to the below, that shows a single pair of characters in it. This code indicates the I2C address of your display.

0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --
I2C Detect Table

If your table is returned blank then you’ve either got a wiring issue or I2C communication isn’t turned on. If you get a table full of characters 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.

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

Downloading And Running The Adafruit Stats Script

Next let’s have a look at the python script and how to install it.

The script is one of the example scripts provided in the Adafruit Python SSD1306 library, with some tweaks. There is a note on the Github page to say that this is a depreciated library, but that doesn’t mean that you can’t use it or that it will no longer work. It just means that they have developed a better or more recent set of libraries. We’re not so much interested in the library as we are in the stats example script, so we’re going to use it anyway.

Download the script by typing in the following commands:

sudo python -m pip install --upgrade pip setuptools wheel
git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
Download The Adafruit OLED Display Library

Next, navigate to your library’s directory:

cd Adafruit_Python_SSD1306

Then run the setup script to install the library. Make sure that the python version you choose here matches the version you are going to run the actual script in.

sudo python3 setup.py install
Run The setup Script

Next navigate to the examples directory in the Adafruit directory:

cd examples

Then execute the stats script:

python3 stats.py

You should then see your Pi’s stats shown on the display.

Basic Stats Example Script Running

You can see the text isn’t that clear, there are a few weird characters on the display and the CPU temperature isn’t displayed. So we’re going to try and fix those in the following section.

Adjusting The Display Content & Layout

The following steps are done on the Raspberry Pi OS desktop and edits to the script are made in Thonny Python IDE (which comes pre-installed).

Open up the examples folder in the Adafruit library which you were working on in the previous step and use the Thonny Python IDE to open up the stats script so that you can edit it.

Copy these two portions of the script below and paste them into your script on your Pi.

Add the following two lines to the script at the end of the “# Shell scripts for system monitoring from here” section

cmd = "vcgencmd measure_temp |cut -f 2 -d '='"
temp = subprocess.check_output(cmd, shell = True )

Replace the following lines in the “# Write two lines of text” section.

draw.text((x, top), "IP: " + str(IP,'utf-8'), font=font, fill=255)
draw.text((x, top+8), str(CPU,'utf-8') + " " + str(temp,'utf-8') , font=font, fill=255)
draw.text((x, top+16), str(MemUsage,'utf-8'), font=font, fill=255)
draw.text((x, top+25), str(Disk,'utf-8'), font=font, fill=255)
Editing The Content of the Script

Have a look at the video at the begining if you’re unsure about which lines to replace or change.

Running the script you can now see that the characters are gone and the temperature is being displayed alongside the CPU load:

Display adjusted to remove characters

This is where I left the display in my original video, but it looks a lot better if you use a better font, which allows the text to fit into the width limit and uses the full height of the display, so let’s look at that next.

First, let’s change the display size so that we’re using all of the display’s pixels so that the text is a bit clearer. This display is actually a 128 x 64 display, not the 128 x 32 display which is set by default.

Comment out the line near the top which sets the display size to 128 x 32:

# disp = Adafruit_SSD1306.SSD1306_128_32(rst=RST)

And then uncomment the line which sets the display size to 128 x 64:

disp = Adafruit_SSD1306.SSD1306_128_64(rst=RST)
Editing the Display Size

If you run the script you’ll now see that the text is much clearer, but it all bunched up in the top half.

OLED Stats Display Squashed Into Top Half

We can play around with the spacing, but this font is just not great for this stats layout. So let’s now look at changing the font.

Download the font PixelOperator.ttf from https://www.dafont.com/pixel-operator.font and then unzip the contents of the download.

Downloading The New Font

Look for the standard pixel operator font and copy the font into the same directory as your stats script.

You’ll then need to copy the filename of your font, along with the extension, to put into the script.

Comment out the line which loads the default font:

# Load default font.
# font = ImageFont.load_default()

Uncomment the line which loads the replacement font and paste your filename into it, keeping the inverted commas on either side. You can also play around with the font size by editing the number after the font name, I’ve used 16 here.

# Alternatively load a TTF font.  Make sure the .ttf font file is in the same directory as the python script!
# Some other nice fonts to try: http://www.dafont.com/bitmap.php
# font = ImageFont.truetype('PixelOperator.ttf', 16)
Copying New Font In Script

If you now run the script you’ll see that the text is a bit taller and is in your new font, but it’s still bunched up at the top of the display. So the last thing we need to do is adjust the layout.

New Font Being Displayed on OLED Stats Display

Adjusting the layout is a bit of a guessing game until you get it looking the way you’d like it to, or just copy the numbers I’ve used:

draw.text((x, top+2), "IP: " + str(IP,'utf-8'), font=font, fill=255)
draw.text((x, top+18), str(CPU,'utf-8') + " " + str(temp,'utf-8') , font=font, fill=255)
draw.text((x, top+34), str(MemUsage,'utf-8'), font=font, fill=255)
draw.text((x, top+50), str(Disk,'utf-8'), font=font, fill=255)
Editing The Display Spacing

When you’re done, you should now have a clear OLED stats display running on your Pi.

OLED Stats Display Now Showing The Correct Items and Spacing

This script will continue to run and update the display as long as you’ve got your IDE open. But we want it to run all the time and run on startup, so there’s one last thing to do.

Setting The Script To Run Automatically On Startup

Copy the OLED stats display script and the font into your home directory.

Copy Script and Font Into Home Directory

Open crontab by typing the following command into your terminal:

crontab -e

If this is the first time you’re opening crontab then select 1 as your editor and hit enter.

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

@reboot python3 /home/pi/stats.py &
Edit Crontab To Automatically Run On Startup

You might need to change the directory to suit the directory that you’ve got your script saved into.

Also don’t forget the & at the end to tell the Pi to continue starting up and run the script in the background.

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

If it is all working correctly then you should have a working stats display which starts up automatically each time your Pi boots up.

Programming An OLED Stats Display For Your Raspberry Pi

If you’re using an Ice Tower with your stats display, plug the fan’s power cables in to the 5V and GND GPIO pins next to the display’s connections as shown below.

Plug Ice Tower Fan Into Available IO Port

Let me know what you think of this OLED stats display in the comments section below and let me know what you’re using it for. Have you built it into your own case?

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.

15 COMMENTS

  1. Hi Michael,

    Thank you again for a great tutorial and for the amazing case!

    One note though, pip3 isn’t always installed, so I suggest adding the ‘sudo apt install python3-pip’ command before entering the ‘sudo pip3…’ command.

    Arik

  2. Hi Michael

    Great work as usual, just a slight issue.

    If I add the script in the crontab and reboot, the display flashes up and goes blank.

    If i run the python script from the home directory –
    python3 /home/pi/Adafruit_Python_SSD1306/examples/stats.py

    I get the following error

    Traceback (most recent call last):
    File “/home/pi/Adafruit_Python_SSD1306/examples/stats.py”, line 103, in
    font = ImageFont.truetype(‘PixelOperator.ttf’, 16)
    File “/home/pi/.local/lib/python3.7/site-packages/PIL/ImageFont.py”, line 853, in truetype
    return freetype(font)
    File “/home/pi/.local/lib/python3.7/site-packages/PIL/ImageFont.py”, line 850, in freetype
    return FreeTypeFont(font, size, index, encoding, layout_engine)
    File “/home/pi/.local/lib/python3.7/site-packages/PIL/ImageFont.py”, line 210, in __init__
    font, size, index, encoding, layout_engine=layout_engine
    OSError: cannot open resource

    However if i run python3 stats.py directly from the examples folder it works..

    Any ideas?

    • It looks like it’s not able to find the font you’re using within the folder you’re running the script from.

  3. Thank you very much for this instruction and fun little project.
    I love this little displays, I am glad I have now one connected to my Octopi Raspi. 🙂

    • I have never tried to do so, but you can set the script to display any metrics that are made available by other applications. So I would imagine you could pull data from pi-hole if you wanted to.

  4. Great Tutorial my display works flawlessly thanks to all your information and steps. Great Job. The only thing I had to troubleshoot was I received two errors. Once I installed the following two packages worked perfectly.

    sudo apt-get install libopenjp2-7
    sudo apt install libtiff5

    Thanks Again!!!!

    • Thanks for the feedback Matthew. I haven’t seen those packages come up previously, what operating system/version are you running?

  5. Thanks so much for making this follow up tutorial because I was having a little bit of trouble using the original one you created. I’m new to the world of R-PI and was extremely excited when cases arrived today. Love this case by the way! I immediately got started using your tutorial and I have to say that everything worked great with the exception for the final step. It’s probably my fault because I opted to use a direct path to the stats.py file in the example folder rather than placing it and the font file on my desktop. Nonetheless, I cannot get the script to auto run upon reboot. Alternatively, I did try it from the home screen as describe in your instructions and it still did not work. Any idea what could be wrong? The info and path I entered and saved in the crontab file was @reboot python3 /home/pi/Adafruit_Python_SSD1306/examples/stats.py & . Again, as I mentioned, I did try @reboot python3 /home/pi/stats.py & and placed the two files on the home screen, but it still did not work.

  6. Great write up! im very new at all of this but followed along and all is working well.

    Is there a way to have the display turn off/clear when the Pi is shutdown? Then if i follow the last steps and have the script run on boot, will it auto turn on?

    • You’d probably have to run a pkill command to stop the current script and then run another script to “blank out” the display. You could also try using one of the GPIO pins to switch the power to the display on or off.

  7. In crontab after I try to exit it says “ File name to write: /tmp/crontab.LfxgzD/crontab” and it gives me a bunch of options but you never said which one to do. Would you please tell me?

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Latest posts

Solar Powered Crypto Miner Using A Raspberry Pi

A common question I’ve seen across a number of my Raspberry Pi projects and videos is whether you can use a Raspberry Pi to...

Connect and Program An OLED Stats Display For Your Raspberry Pi

In this guide, I'll show you how to program a 128x64 I2C OLED stats display as a quick dashboard for your Raspberry Pi. I...

Bitcoin Ticker Using An ESP32 and OLED Display

Today we're going to be making a desktop Bitcoin ticker using an ESP32 development board and an OLED display. This one has been programmed...

Related posts

Want to stay up to date with the latest news?

We would love to hear from you! Please fill in your details and we will stay in touch. It's that simple!