Step‑by‑Step Guide: Connect and Use an OLED Display with Raspberry Pi

OLED Module Overview

The guide uses a 128×64 I2C OLED screen (available in white, yellow, or blue) that connects to a Raspberry Pi via four pins: VCC, GND, SDA, and SCL.

Enable I2C on Raspberry Pi

By default the Pi’s I2C bus is disabled. Run the following commands to install required tools and enable the interface:

$ sudo apt-get install -y python-smbus
$ sudo apt-get install -y i2c-tools
$ sudo raspi-config

In the configuration menu, select the option to enable I2C and reboot if prompted.

Install the Adafruit SSD1306 Python Library

Clone the library repository and install it for Python 3:

$ git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
$ cd Adafruit_Python_SSD1306
$ sudo python3 setup.py install

(Use the appropriate command for Python 2 if needed.)

Detect the OLED I2C Address

After installing the library, run i2cdetect to locate the OLED’s address: $ i2cdetect -y 1 The output should show 0x3C as the device address. On older Raspberry Pi 1 models, use $ i2cdetect -y 0 instead.

Display Images and Text

The library’s examples directory contains several ready‑to‑run scripts (e.g., animate.py, buttons.py, image.py, shapes.py, stats.py). Execute a script with: $ python3 shapes.py Each script demonstrates different drawing capabilities on the OLED screen.

Adapting to Different Screen Sizes

By default the example code assumes a 128×32 display. Within each Python file there are two lines—one for 128×32 and one for 128×64—where the unused line is commented out with #. Remove the comment character from the line that matches your screen size to enable proper rendering.