# Adafruit PiOLED - 128x32 Mini OLED for Raspberry Pi

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/042/204/medium800/raspberry_pi_3527_top_demo_ORIG.jpg?1496265779)

If you're looking for the most compact lil' display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The Adafruit PiOLED is your little OLED pal, ready to snap onto any and all Raspberry Pi computers, to give you a little display. The PiOLED comes with a monochrome 128x32 OLED, with sharp white pixels. The OLED uses only the I2C pins so you have plenty of GPIO connections available for buttons, LEDs, sensors, etc. It's also nice and compact so it will fit into any case.

![](https://cdn-learn.adafruit.com/assets/assets/000/042/205/medium800/raspberry_pi_3527_iso_02_ORIG.jpg?1496265795)

These displays are small, only about 1" diagonal, but very readable due to the high contrast of an OLED display. This screen is made of 128x32 individual white OLED pixels and because the display makes its own light, no backlight is required. This reduces the power required to run the OLED and is why the display has such high contrast; we really like this miniature display for its crispness!

Using the display is very easy, we have a Python library for the SSD1306 chipset. Our example code allows you to draw images, text, whatever you like, using the Python imaging library. Our tests showed 30 FPS update rates so you can do animations or simple video.

![](https://cdn-learn.adafruit.com/assets/assets/000/042/206/medium800/raspberry_pi_3527_bottom_ORIG.jpg?1496265809)

 **Comes completely pre-assembled and tested** so you don't need to do anything but plug it in and install our Python code! Works with any Raspberry Pi computer, including the original Pi 1, B+, Pi 2, Pi 3, Pi 4, and Pi Zero.

# Adafruit PiOLED - 128x32 Mini OLED for Raspberry Pi

## Usage

## Install CircuitPython 

This guide assumes that you've gotten your Raspberry Pi up and running, and have CircuitPython installed. If not, check out the guide:

[CircuitPython Installation Guide](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi)
To [install the library for the Pi OLED](https://github.com/adafruit/Adafruit_CircuitPython_SSD1306), enter the following into the terminal:

```
sudo pip3 install adafruit-circuitpython-ssd1306
```

If that complains about pip3 not being installed, then run this first to install it:

```
sudo apt-get install python3-pip

```

We also need PIL to allow using text with custom fonts. There are several system libraries that PIL relies on, so installing via a package manager is the easiest way to bring in everything:

```
sudo apt-get install python3-pil
```

## Enable I2C

[To enable i2c, you can follow our detailed guide on configuring the Pi with I2C support here.](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi#enable-i2c-and-spi-3-5)

After you've enabled I2C you will need to shutdown with  **`sudo shutdown -h now`**

Once the Pi has halted, plug in the PiOLED. Now you can power the Pi back up, and log back in. Run the following command from a terminal prompt to scan/detect the I2C devices

**`sudo i2cdetect -y 1`**

You should see the following, indicating that address  **0x3c**  (the OLED display) was found

![](https://cdn-learn.adafruit.com/assets/assets/000/074/057/medium800/adafruit_products_i2c.png?1554480832)

## Verify I2C Device

You can run our stats example, which will query the Pi for details on CPU load, disk space, etc. and print it on the OLED.

Create a new file with  **nano ~pi/stats.py**  and paste this code below in! Then save it.

https://github.com/adafruit/Adafruit_CircuitPython_SSD1306/blob/main/examples/ssd1306_stats.py

Run `sudo python3 stats.py` and you should see something like the following image:

![](https://cdn-learn.adafruit.com/assets/assets/000/074/049/medium800/adafruit_products_raspberry_pi_3527_top_demo_ORIG.jpg?1554472624)

# Running Stats on Boot

You can pretty easily make it so this handy program runs every time you boot your Pi.

The fastest/easiest way is to put it in  **/etc/rc.local**

Run **sudo nano /etc/rc.local** and add the line

`sudo python3 /home/pi/stats.py &`

on its own line right before **exit 0**

Then save and exit. Reboot to verify that the screen comes up on boot!

![](https://cdn-learn.adafruit.com/assets/assets/000/074/056/medium800/adafruit_products_1__pi_oledpi_____ssh_.png?1554480418)

[For more advanced usage, check out our linux system services guide](../../../../running-programs-automatically-on-your-tiny-computer/)

## Library Usage

In the [examples subdirectory of the Adafruit\_CircuitPython\_SSD1306 repository](https://github.com/adafruit/Adafruit_CircuitPython_SSD1306/tree/master/examples), you'll find examples which demonstrate the usage of the library.

To help you get started, I'll walk you through the  **stats.py** code you ran earlier, that way you can use this file as a basis of a future project.

```
import time
import subprocess

from board import SCL, SDA
import busio
from PIL import Image, ImageDraw, ImageFont
import adafruit_ssd1306
```

First, a few Python modules are imported. This includes the `adafruit_ssd1306` module which contains the OLED driver classes.

To draw images, shapes, and text/fonts, the code imports some of the **P** ython **I** maging **L** ibrary's modules like `Image`, `ImageDraw`, and `ImageFont`.

```
# Create the I2C interface.
i2c = busio.I2C(SCL, SDA)

# Create the SSD1306 OLED class.
# The first two parameters are the pixel width and pixel height.  Change these
# to the right size for your display!
disp = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
```

Since the PiOLED is a 128x32 I2C only device, the screen size and the i2c interface are passed to the `adafruit_ssd.SSD1306_I2C` class. 

```
# Clear display.
disp.fill(0)
disp.show()

# Create blank image for drawing.
# Make sure to create image with mode '1' for 1-bit color.
width = disp.width
height = disp.height
image = Image.new('1', (width, height))

# Get drawing object to draw on image.
draw = ImageDraw.Draw(image)

# Draw a black filled box to clear the image.
draw.rectangle((0, 0, width, height), outline=0, fill=0)
```

The next chunk of code clears the display by inverting its fill with `fill(0)` and then writing to the display with `show()`.

Then it will configure a PIL drawing class to prepare for drawing graphics. Notice that the image buffer is created in 1-bit mode with the `'1'` parameter, this is important because the display only supports black and white colors.

We then re-draw a large black rectangle to clear the screen. In theory we don't have to clear the screen again, but its a good example of how to draw a shape!

```
# Draw some shapes.
# First define some constants to allow easy resizing of shapes.
padding = -2
top = padding
bottom = height-padding
# Move left to right keeping track of the current x position for drawing shapes.
x = 0


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

# 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('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 9)
```

Once the display is initialized and a drawing object is prepared, you can draw shapes, text and graphics using [PIL's drawing commands](http://effbot.org/imagingbook/imagedraw.htm). We'll define some constraints based on the height and width of the display to allow for easy resizing of shapes.

Then, the code loads the `default` font, which works fine, but there's other fonts you can load.

Next the code loads a built-in default font and draws a few lines of text. You can also load your own TrueType font and use it to render fancy text in any style you like

```
while True:

    # Draw a black filled box to clear the image.
    draw.rectangle((0, 0, width, height), outline=0, fill=0)

    # Shell scripts for system monitoring from here:
    # https://unix.stackexchange.com/questions/119126/command-to-display-memory-usage-disk-usage-and-cpu-load
    cmd = "hostname -I | cut -d\' \' -f1"
    IP = subprocess.check_output(cmd, shell=True).decode("utf-8")
    cmd = "top -bn1 | grep load | awk '{printf \"CPU Load: %.2f\", $(NF-2)}'"
    CPU = subprocess.check_output(cmd, shell=True).decode("utf-8")
    cmd = "free -m | awk 'NR==2{printf \"Mem: %s/%s MB  %.2f%%\", $3,$2,$3*100/$2 }'"
    MemUsage = subprocess.check_output(cmd, shell=True).decode("utf-8")
    cmd = "df -h | awk '$NF==\"/\"{printf \"Disk: %d/%d GB  %s\", $3,$2,$5}'"
    Disk = subprocess.check_output(cmd, shell=True).decode("utf-8")

    # Write four lines of text.

    draw.text((x, top+0), "IP: "+IP, font=font, fill=255)
    draw.text((x, top+8), CPU, font=font, fill=255)
    draw.text((x, top+16), MemUsage, font=font, fill=255)
    draw.text((x, top+25), Disk, font=font, fill=255)

    # Display image.
    disp.image(image)
    disp.show()
    time.sleep(.1)
```

Using the subprocess class, python can utilize linux commands to access the Pi's system information. This loop updates the screen at 10 times a second.  
  
That's all there is to the **stats.py** code!

## Speeding up the Display

For the best performance, especially if you are doing fast animations, you'll want to tweak the I2C core to run at 1MHz. By default it may be 100KHz or 400KHz

To do this edit the config with `sudo nano /boot/config.txt`

and add to the end of the file

`dtparam=i2c_baudrate=1000000`

![](https://cdn-learn.adafruit.com/assets/assets/000/074/058/medium800/adafruit_products_i2c_baud.png?1554480868)

# Adafruit PiOLED - 128x32 Mini OLED for Raspberry Pi

## Downloads

# Files

- [EagleCAD PCB files on GitHub](https://github.com/adafruit/Adafruit-PiOLED-128x32-PCB)
- [UG-2832HSWEG02](https://cdn-shop.adafruit.com/datasheets/UG-2832HSWEG02.pdf) Datasheet
- [SSD1306](http://www.adafruit.com/datasheets/SSD1306.pdf) Datasheet
- [Fritzing object in Adafruit Fritzing Library](https://github.com/adafruit/Fritzing-Library/)

# Schematic & Fabrication Print
![](https://cdn-learn.adafruit.com/assets/assets/000/042/248/medium800/adafruit_products_schem.png?1496376981)

![](https://cdn-learn.adafruit.com/assets/assets/000/042/249/medium800/adafruit_products_fabprint.png?1496376987)


## Featured Products

### Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi

[Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi](https://www.adafruit.com/product/3527)
If you're looking for the most compact li'l display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The **Adafruit...**

In Stock
[Buy Now](https://www.adafruit.com/product/3527)
[Related Guides to the Product](https://learn.adafruit.com/products/3527/guides)

## Related Guides

- [Pi Hole Ad Blocker with Pi Zero W](https://learn.adafruit.com/pi-hole-ad-blocker-with-pi-zero-w.md)
- [Adafruit AD5693R 16-Bit DAC Breakout Board](https://learn.adafruit.com/adafruit-ad5693r-16-bit-dac-breakout-board.md)
- [Adafruit I2C to 8 Channel Solenoid Driver](https://learn.adafruit.com/adafruit-i2c-to-8-channel-solenoid-driver.md)
- [Fisher-Price USB Foot Pedal](https://learn.adafruit.com/fisher-price-usb-foot-pedal.md)
- [Adafruit Voice Bonnet](https://learn.adafruit.com/adafruit-voice-bonnet.md)
- [reef-pi Guide 1: Setup and Demonstration](https://learn.adafruit.com/reef-pi-installation-and-configuration.md)
- [Where's My Friend? A Location-Aware Display with PyPortal and ItsASnap](https://learn.adafruit.com/where-s-my-friend-a-location-display-frame-with-pyportal.md)
- [Adafruit Feather M0 Basic Proto](https://learn.adafruit.com/adafruit-feather-m0-basic-proto.md)
- [Introducing Adafruit Trellis ](https://learn.adafruit.com/adafruit-trellis-diy-open-source-led-keypad.md)
- [Adafruit DVI Sock for Pico](https://learn.adafruit.com/adafruit-dvi-sock-for-pico.md)
- [Adafruit RFM69HCW and RFM9X LoRa Packet Radio Breakouts](https://learn.adafruit.com/adafruit-rfm69hcw-and-rfm96-rfm95-rfm98-lora-packet-padio-breakouts.md)
- [Adafruit Data Logger Shield](https://learn.adafruit.com/adafruit-data-logger-shield.md)
- [Adafruit TMP007 Sensor Breakout](https://learn.adafruit.com/adafruit-tmp007-sensor-breakout.md)
- [Adafruit Mini GPS PA1010D Module](https://learn.adafruit.com/adafruit-mini-gps-pa1010d-module.md)
- [AWS IoT and Adafruit WICED Feather](https://learn.adafruit.com/aws-iot-and-adafruit-wiced-feather.md)