OLED Display Graphics Project - Complete Step-by-Step Guide

SSD1306 128×64 with Arduino Uno in Wokwi

What is This Project?

This project demonstrates how to interface an SSD1306 OLED display (128×64 pixels) with an Arduino Uno microcontroller using the I2C communication protocol. You will learn how to display text, shapes, animations, and graphics patterns on the OLED screen.

What Will You Learn?

How to use I2C communication with Arduino
OLED display programming techniques
Creating text displays with multiple sizes
Drawing geometric shapes (circles, rectangles, triangles)
Implementing animations (bouncing ball)
Creating scrolling text effects
Generating graphics patterns

Prerequisites

Knowledge Requirements:

Basic understanding of Arduino programming
Familiarity with C/C++ syntax
Basic electronics knowledge (voltage, ground, connections)
Understanding of digital communication protocols (helpful but not required)

Software Requirements:

Web browser (Chrome, Firefox, Safari, or Edge)
Internet connection
Wokwi account (free registration)

What is an OLED Display?

OLED stands for Organic Light-Emitting Diode. Unlike LCD displays that require a backlight, each pixel in an OLED display emits its own light. This results in:

Better Contrast: True black pixels (completely off)
Lower Power Consumption: Only lit pixels consume power
Faster Response Time: No liquid crystal delay
Wider Viewing Angles: Clear from any angle

SSD1306 Display Specifications

Specification	Value
Resolution	128 × 64 pixels
Display Type	Monochrome (White/Blue on Black)
Interface	I2C (Two-wire)
Operating Voltage	3.3V - 5V
I2C Address	0x3C or 0x3D
Driver Chip	SSD1306

I2C Communication Protocol

What is I2C?

I2C (Inter-Integrated Circuit) is a serial communication protocol that uses only two wires:

SDA (Serial Data): Carries data between devices
SCL (Serial Clock): Synchronizes data transmission

Advantages of I2C:

Only 2 wires needed (saves Arduino pins)
Multiple devices can share the same bus
Each device has a unique address
Supports data rates up to 400 kHz (Fast Mode)

How I2C Works:

Arduino (Master) sends a START signal
Master sends device address (0x3C for our OLED)
Device acknowledges if present
Master sends commands/data
Device responds
Master sends STOP signal

3. COMPONENTS REQUIRED

Hardware Components

1. Arduino Uno (1 unit)

Description: Arduino Uno is a microcontroller board based on the ATmega328P chip.

Specifications:

Microcontroller: ATmega328P
Operating Voltage: 5V
Digital I/O Pins: 14 (6 PWM outputs)
Analog Input Pins: 6
Flash Memory: 32 KB
SRAM: 2 KB
Clock Speed: 16 MHz

Purpose in Project: Main controller that sends commands and data to the OLED display.

2. SSD1306 OLED Display 128×64 I2C (1 unit)

Description: Compact monochrome display module with I2C interface.

Specifications:

Screen Size: 0.96 inch (typical)
Resolution: 128 pixels (width) × 64 pixels (height)
Colors: Monochrome (White or Blue)
Interface: I2C (4 pins)
Viewing Angle: >160°

Purpose in Project: Visual output device to display text, shapes, and graphics.

3. Jumper Wires (4 units)

Types Needed:

Male-to-Male jumper wires (for breadboard)
Male-to-Female jumper wires (for direct connection)

Suggested Colors:

Red wire: Power (VCC to 5V)
Black wire: Ground (GND to GND)
Green wire: Clock (SCL to A5)
Blue wire: Data (SDA to A4)

Purpose in Project: Connect Arduino pins to OLED display pins.

4. UNDERSTANDING THE COMPONENTS

Arduino Uno Pin Layout

Important Pins for This Project:

Pin Name	Pin Number	Purpose	Connection
5V	Power Rail	Provides 5V power	To OLED VCC
GND	Ground Rail	Common ground	To OLED GND
A4	Analog Pin 4	I2C SDA (Data)	To OLED SDA
A5	Analog Pin 5	I2C SCL (Clock)	To OLED SCL

Why A4 and A5?

On Arduino Uno, the I2C pins are fixed:

A4 is hardwired to SDA
A5 is hardwired to SCL

You cannot use other pins for hardware I2C communication.

OLED Display Pin Layout

Standard 4-Pin I2C OLED:

Pin	Name	Function	Voltage
1	GND	Ground	0V
2	VCC	Power Supply	3.3V - 5V
3	SCL	I2C Clock	Digital Signal
4	SDA	I2C Data	Digital Signal

Note: Some displays may have pins in different orders. Always check the labels on your specific module.

5. CIRCUIT CONNECTIONS (DETAILED)

Connection Table

OLED Pin	Wire Color	Arduino Pin	Description
VCC	Red	5V	Power supply (positive)
GND	Black	GND	Ground (negative)
SCL	Green	A5	I2C Clock line
SDA	Blue	A4	I2C Data line

Visual Connection Diagram OLED Display Arduino Uno

        ┌──────────┐             ┌──────────┐
        │   GND    │────Black────│   GND    │
        │   VCC    │────Red──────│   5V     │
        │   SCL    │────Green────│   A5     │
        │   SDA    │────Blue─────│   A4     │
        └──────────┘             └──────────┘

Why These Specific Pins?

A4 (SDA) and A5 (SCL):

These are the dedicated hardware I2C pins on Arduino Uno
Using hardware I2C is faster and more reliable than software I2C
The Wire library automatically uses these pins

5V vs 3.3V:

Most OLED modules work with both voltages
5V is more common and provides brighter display
Internal voltage regulator on module protects the display

6. SETTING UP WOKWI ENVIRONMENT

What is Wokwi?

Wokwi is an online simulator for Arduino and other microcontrollers. It allows you to:

Build circuits virtually
Write and test code
See real-time simulation
Debug without physical hardware

Creating Your Wokwi Project

Method 1: Using Provided Files (Fastest)

Step 1: Access Wokwi

Open web browser
Navigate to: https://wokwi.com
Click "Sign In" (top right)
Create free account or log in

Step 2: Create New Project

Click "New Project" button
Select "Arduino Uno"
Project workspace opens with default code

Step 3: Load diagram.json

{
  "version": 1,
  "author": "Arduino OLED Graphics Demo",
  "editor": "wokwi",
  "parts": [
    {
      "type": "wokwi-arduino-uno",
      "id": "uno",
      "top": 0,
      "left": 0,
      "attrs": {}
    },
    {
      "type": "wokwi-ssd1306",
      "id": "oled1",
      "top": -120,
      "left": 100,
      "attrs": {
        "i2cAddress": "0x3C"
      }
    }
  ],
  "connections": [
    [
      "oled1:GND",
      "uno:GND.1",
      "black",
      [
        "v0"
      ]
    ],
    [
      "oled1:VCC",
      "uno:5V",
      "red",
      [
        "v0"
      ]
    ],
    [
      "oled1:SCL",
      "uno:A5",
      "green",
      [
        "v0"
      ]
    ],
    [
      "oled1:SDA",
      "uno:A4",
      "blue",
      [
        "v0"
      ]
    ]
  ],
  "dependencies": {}
}

Look for "diagram.json" tab at top of workspace
Click on it to open
Select ALL existing content (Ctrl+A or Cmd+A)
Press Delete to clear it
Open the provided diagram.json file
Copy ALL content (Ctrl+C or Cmd+C)
Paste into Wokwi diagram.json tab (Ctrl+V or Cmd+V)
Circuit appears automatically with all connections

Step 4: Load Arduino Code

/*

 * OLED Display Graphics (SSD1306 128x64) with Arduino Uno

 * This sketch demonstrates various graphics capabilities including:

 * - Text display

 * - Shapes (rectangles, circles, lines)

 * - Animations

 * - Pixel manipulation

*/

#include <Wire.h>

#include <Adafruit_GFX.h>

#include <Adafruit_SSD1306.h>

// OLED display dimensions

#define SCREEN_WIDTH 128

#define SCREEN_HEIGHT 64

#define OLED_RESET -1  // Reset pin (or -1 if sharing Arduino reset pin)

#define SCREEN_ADDRESS 0x3C // I2C address for most SSD1306 displays

// Create display object

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

void setup() {

  Serial.begin(9600);

  // Initialize the OLED display

  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {

    Serial.println(F("SSD1306 allocation failed"));

    for(;;); // Don't proceed, loop forever

}

  // Clear the display buffer

  display.clearDisplay();

  display.display();

  delay(1000);

  Serial.println(F("OLED Display Initialized!"));

}

void loop() {

  // Demo 1: Text Display

  displayTextDemo();

  delay(2000);

  // Demo 2: Shapes

  displayShapesDemo();

  delay(2000);

  // Demo 3: Animation

  displayAnimationDemo();

  delay(2000);

  // Demo 4: Scrolling Text

  displayScrollingText();

  delay(2000);

  // Demo 5: Graphics Pattern

  displayGraphicsPattern();

  delay(2000);

}

// Demo 1: Display various text sizes and styles

void displayTextDemo() {

  display.clearDisplay();

  // Title

  display.setTextSize(1);

  display.setTextColor(SSD1306_WHITE);

  display.setCursor(0, 0);

  display.println(F("Text Display Demo"));

  display.drawLine(0, 10, SCREEN_WIDTH, 10, SSD1306_WHITE);

  // Small text

  display.setTextSize(1);

  display.setCursor(0, 15);

  display.println(F("Size 1 Text"));

  // Medium text

  display.setTextSize(2);

  display.setCursor(0, 28);

  display.println(F("Size 2"));

  // Large text

  display.setTextSize(3);

  display.setCursor(0, 45);

  display.println(F("Big"));

  display.display();

}

// Demo 2: Display various shapes

void displayShapesDemo() {

  display.clearDisplay();

  // Title

  display.setTextSize(1);

  display.setTextColor(SSD1306_WHITE);

  display.setCursor(0, 0);

  display.println(F("Shapes Demo"));

  display.drawLine(0, 10, SCREEN_WIDTH, 10, SSD1306_WHITE);

  // Rectangle

  display.drawRect(5, 15, 30, 20, SSD1306_WHITE);

  // Filled Rectangle

  display.fillRect(40, 15, 30, 20, SSD1306_WHITE);

  // Circle

  display.drawCircle(85, 25, 10, SSD1306_WHITE);

  // Filled Circle

  display.fillCircle(110, 25, 10, SSD1306_WHITE);

  // Triangle

  display.drawTriangle(10, 55, 25, 40, 40, 55, SSD1306_WHITE);

  // Filled Triangle

  display.fillTriangle(50, 55, 65, 40, 80, 55, SSD1306_WHITE);

  // Lines

  display.drawLine(90, 40, 120, 55, SSD1306_WHITE);

  display.drawLine(120, 40, 90, 55, SSD1306_WHITE);

  display.display();

}

// Demo 3: Simple animation - bouncing ball

void displayAnimationDemo() {

  int x = 64;

  int y = 32;

  int dx = 2;

  int dy = 2;

  int radius = 5;

  for(int i = 0; i < 100; i++) {

    display.clearDisplay();

    // Title

    display.setTextSize(1);

    display.setCursor(0, 0);

    display.println(F("Animation Demo"));

    display.drawLine(0, 10, SCREEN_WIDTH, 10, SSD1306_WHITE);

    // Draw ball

    display.fillCircle(x, y, radius, SSD1306_WHITE);

    // Update position

    x += dx;

    y += dy;

    // Bounce off walls

    if(x + radius >= SCREEN_WIDTH || x - radius <= 0) {

      dx = -dx;

}

    if(y + radius >= SCREEN_HEIGHT || y - radius <= 12) {

      dy = -dy;

}

    display.display();

    delay(30);

}

}

// Demo 4: Scrolling text

void displayScrollingText() {

  display.clearDisplay();

  display.setTextSize(2);

  display.setTextColor(SSD1306_WHITE);

  // Display scrolling message

  for(int x = SCREEN_WIDTH; x > -200; x -= 2) {

    display.clearDisplay();

    display.setCursor(x, 25);

    display.println(F("Scrolling!"));

    display.display();

    delay(20);

}

}

// Demo 5: Graphics pattern

void displayGraphicsPattern() {

  display.clearDisplay();

  // Title

  display.setTextSize(1);

  display.setCursor(0, 0);

  display.println(F("Pattern Demo"));

  display.drawLine(0, 10, SCREEN_WIDTH, 10, SSD1306_WHITE);

  // Draw a grid pattern

  for(int i = 0; i < SCREEN_WIDTH; i += 10) {

    display.drawLine(i, 12, i, SCREEN_HEIGHT, SSD1306_WHITE);

}

  for(int i = 12; i < SCREEN_HEIGHT; i += 10) {

    display.drawLine(0, i, SCREEN_WIDTH, i, SSD1306_WHITE);

}

  display.display();

  delay(1500);

  // Draw concentric circles

  display.clearDisplay();

  display.setTextSize(1);

  display.setCursor(0, 0);

  display.println(F("Circles"));

  display.drawLine(0, 10, SCREEN_WIDTH, 10, SSD1306_WHITE);

  for(int r = 5; r < 30; r += 5) {

    display.drawCircle(64, 36, r, SSD1306_WHITE);

}

  display.display();

}

Click "sketch.ino" tab
Select ALL existing content
Delete it
Open the provided oled_display_project.ino file
Copy ALL content
Paste into Wokwi sketch.ino tab

Step 5: Add Libraries

Click "+" button next to file tabs
Select "libraries.txt"
Paste the content from provided libraries.txt file
Save the file

Step 6: Start Simulation

Click green "Start Simulation" button (play icon)
OLED display should initialize
Watch demos cycle automatically

7. CODE EXPLANATION (LINE BY LINE)

Section 1: Library Includes

cpp

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Line 1: Include Wire library for I2C communication Line 2: Include graphics library for drawing functions Line 3: Include SSD1306-specific library

Section 2: Constants and Definitions

cpp

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1#define SCREEN_ADDRESS 0x3C

SCREEN_WIDTH: Display width in pixels (128) SCREEN_HEIGHT: Display height in pixels (64) OLED_RESET: Reset pin configuration (-1 = shared reset) SCREEN_ADDRESS: I2C address (0x3C or 0x3D)

Section 3: Display Object Creation

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

Creates display object with specified dimensions and I2C interface.

Key Functions Used

display.begin() - Initialize the display display.clearDisplay() - Clear the display buffer display.display() - Push buffer to the screen display.setTextSize() - Set text size (1-3) display.setCursor() - Set text position display.println() - Print text display.drawRect() - Draw rectangle outline display.fillRect() - Draw filled rectangle display.drawCircle() - Draw circle outline display.fillCircle() - Draw filled circle display.drawLine() - Draw line display.drawTriangle() - Draw triangle

8. STEP-BY-STEP IMPLEMENTATION

Phase 1: Environment Setup (5 minutes)

Open web browser and go to wokwi.com
Log in or create account
Click "New Project" → "Arduino Uno"
Verify starting point (Arduino appears, default code present)

Phase 2: Circuit Construction (10 minutes)

Using diagram.json:

Click "diagram.json" tab
Delete all content
Paste provided diagram.json
Circuit appears automatically

Manual Wiring:

Add OLED display (search "SSD1306")
Connect VCC to 5V (red wire)
Connect GND to GND (black wire)
Connect SCL to A5 (green wire)
Connect SDA to A4 (blue wire)

Phase 3: Library Installation (3 minutes)

Create "libraries.txt" file
Add two lines:
- Adafruit SSD1306
- Adafruit GFX Library
Save file

Phase 4: Code Implementation (5 minutes)

Click "sketch.ino" tab
Delete default code
Paste provided Arduino code
Save project with name

Phase 5: Testing and Validation (7 minutes)

Click green "Start Simulation" button
Watch for display initialization
Observe demo cycle:
- Text Display Demo (2 seconds)
- Shapes Demo (2 seconds)
- Animation Demo (3 seconds)
- Scrolling Text (2 seconds)
- Graphics Pattern (2 seconds)
Open Serial Monitor (should show "OLED Display Initialized!")
Verify smooth animations and clear graphics

9. TESTING AND VERIFICATION

Visual Tests

Test 1: Display Clarity

Text should be sharp and readable
No flickering or ghosting
Consistent brightness

Test 2: Shape Accuracy

Rectangles have clean corners
Circles are properly round
Triangles have straight edges

Test 3: Animation Smoothness

Ball moves without jerking
Bounces look natural
Consistent frame rate

Test 4: Scrolling

Smooth left motion
No jumping or stuttering
Text stays aligned

Functional Tests

Initialization Test:

Serial Monitor shows "OLED Display Initialized!"
Appears within 2 seconds
No error messages

Demo Sequence Test:

All 5 demos execute in order
Correct timing (2 seconds each, animation 3 seconds)
Cycle repeats continuously

OLED Display Graphics (SSD1306 128×64) using arduino uno project with step by step instructions in wowki