Interface SSD1306 OLED Display with STM32 Using I2C

The SSD1306 OLED display is a popular choice for embedded projects due to its compact size, excellent contrast, and low power consumption. It is commonly available as a 0.96-inch 128×64 pixel module, and can communicate using either I2C or SPI protocols.

In this tutorial, we’ll focus on interfacing the SSD1306 OLED display with STM32 microcontrollers using the I2C interface. We will configure the I2C peripheral in STM32CubeMX, generate initialization code using the HAL library, and then write a simple driver to display text and graphics on the OLED screen.

This step-by-step STM32 SSD1306 OLED I2C tutorial is beginner-friendly and works across most STM32 series, including F1, F4, and H7 families. Whether you’re creating a real-time sensor dashboard or adding a stylish display to your project, this tutorial will help you get started quickly.

Recommended Resources:

You can also take a look at the other Oled and LCD Displays interfaced with STM32.

• Interface SH1106 1.3″ OLED with STM32
• How to Port U8G2 Graphics Library to STM32
• Interface LCD1602 Display with STM32
• Interface Graphic LCD ST7920 with STM32
• Interface GC9A01 Round Display with STM32

I am going to use a 0.96″ SSD1306 OLED display and STM32f103c8t6 for this project.

SSD1306 OLED Overview & I2C Advantages

What Is the SSD1306 OLED Display?

The SSD1306 is a monochrome OLED driver IC used in the popular 0.96-inch 128×64 pixel modules found across embedded and IoT projects.

Unlike LCDs, OLED pixels are self-emissive (no backlight is needed), which delivers deep blacks, high contrast, and wide viewing angles even at low supply currents. Most breakout modules support both I2C and SPI; this tutorial covers the I2C variant.

Key Specifications at a Glance

Why Use I2C with STM32?

The I2C interface is a two-wire serial communication protocol that uses only SDA (data) and SCL (clock) lines. Most STM32 microcontrollers have multiple I2C peripherals built in, making them ideal for connecting displays and sensors with minimal wiring.

Using I2C with the SSD1306 OLED has several advantages:

• Fewer GPIO Pins: Only two lines are required, which leaves more pins available for other peripherals.
• Built-in STM32 HAL Support: STM32CubeMX can automatically configure I2C peripherals, making initialization easier.
• Multiple Devices on One Bus: You can connect several I2C devices (e.g., sensors and displays) to the same bus, reducing complexity.
• Stable and Reliable Communication: I2C is well-supported by STM32 HAL drivers, so data transfer to the OLED is straightforward and efficient.

For these reasons, I2C is the most common and beginner-friendly method to interface the SSD1306 display with STM32 microcontrollers.

Wiring SSD1306 OLED to STM32

The first practical step in this project is to connect the SSD1306 OLED display to the STM32 board. Since we are using the I2C communication protocol, the wiring is very straightforward. We only need two I2C pins (SDA and SCL) along with power and ground connections.

The image below shows how the STM32 is connected to the SSD1306 Oled Display.

As shown in the image above, the connection is as follows:

The SSD1306 OLED modules typically operate at either 3.3 V or 5 V, depending on the breakout board. Many modules come with an onboard regulator, which allows them to be powered by 5 V while internally running at 3.3 V.

For STM32, which usually operates at 3.3 V logic levels, it is safest to:

• Use a 3.3 V supply to power the OLED if supported.
• If the OLED requires 5 V for VCC, make sure the I2C lines are 5 V tolerant on your STM32 pins (many F1/F4 pins are).
• Alternatively, use level shifters if your MCU pins are not 5 V tolerant.

CubeMX Setup, Driver Code & Results

Once the OLED is connected to the STM32 board, the next step is to configure the I2C peripheral using STM32CubeMX.

Clock Configuration

Below is the image showing the Clock configuration for the project.

The system is clocked by an external 8MHz HSE Crystal, which is present on the Dev board. We will use the PLL to run the system at maximum 72MHz clock.

I2C Configuration (Fast Mode, 400 kHz)

Below is the image showing the I2C configuration.

I am using I2C1 for the project.

• Set the I2C in the FAST MODE, as it is required for the OLED Display. The clock speed will automatically set to 400KHz.
• The SCL and SDA Pins will get automatically selected. Here PB6 is configured as SCL and PB7 is configured as SDA.

Driver Setup — ssd1306.c & ssd1306.h

Copy ssd1306.c, ssd1306.h, fonts.c, and fonts.h from the downloaded project into the Src and Inc folders of your CubeIDE project.

Open ssd1306.c and confirm the I2C handler matches what CubeMX generated:

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

If you used I2C2 or I2C3 in CubeMX, change hi2c1 to match. Then confirm the resolution defines in ssd1306.h:

#define SSD1306_WIDTH   128
#define SSD1306_HEIGHT   64

#define SSD1306_WIDTH   128
#define SSD1306_HEIGHT   64

Display Strings on the SSD1306

#include "ssd1306.h"
#include "fonts.h"

int main()
{
  .....
  SSD1306_Init (); // initialise the display 
  SSD1306_GotoXY (10,10); // goto 10, 10 
  SSD1306_Puts ("HELLO", &Font_11x18, 1); // print Hello 
  SSD1306_GotoXY (10, 30); 
  SSD1306_Puts ("WORLD !!", &Font_11x18, 1); 
  SSD1306_UpdateScreen(); // update screen
  while (1) { }
}  

#include "ssd1306.h"
#include "fonts.h"

int main()
{
  .....
  SSD1306_Init (); // initialise the display 
  SSD1306_GotoXY (10,10); // goto 10, 10 
  SSD1306_Puts ("HELLO", &Font_11x18, 1); // print Hello 
  SSD1306_GotoXY (10, 30); 
  SSD1306_Puts ("WORLD !!", &Font_11x18, 1); 
  SSD1306_UpdateScreen(); // update screen
  while (1) { }
}  

SSD1306_Init() sends the full initialization sequence to the OLED. SSD1306_GotoXY(x, y) sets the pixel cursor. SSD1306_Puts() writes to the internal framebuffer. SSD1306_UpdateScreen() must be called to push the framebuffer to the display — nothing appears on screen until it is.

Display Numbers and Floats

Any display does not support printing the numbers directly on it. Instead we need to change the number into the equivalent Ascii characters with sprintf before sending:

Below the code shows how to print integer and floats.

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"  // for sprintf

int main()
{
  .....
  int num = 123456; float flt = 123.45;
  char bufnum[7]; char bufflt[7];
  SSD1306_Init (); // initialise the display 
  sprintf (bufnum, "%d", num);
  sprintf (bufflt, "%.2f", flt);
  SSD1306_GotoXY (10,10); // goto 10, 10 
  SSD1306_Puts (bufnum, &Font_11x18, 1); // print Hello 
  SSD1306_GotoXY (10, 30); 
  SSD1306_Puts (bufflt, &Font_11x18, 1); 
  SSD1306_UpdateScreen(); // update screen
  while (1) { }
} 

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"  // for sprintf

int main()
{
  .....
  int num = 123456; float flt = 123.45;
  char bufnum[7]; char bufflt[7];
  SSD1306_Init (); // initialise the display 
  sprintf (bufnum, "%d", num);
  sprintf (bufflt, "%.2f", flt);
  SSD1306_GotoXY (10,10); // goto 10, 10 
  SSD1306_Puts (bufnum, &Font_11x18, 1); // print Hello 
  SSD1306_GotoXY (10, 30); 
  SSD1306_Puts (bufflt, &Font_11x18, 1); 
  SSD1306_UpdateScreen(); // update screen
  while (1) { }
} 

• The sprintf function is used to convert the integer(%d) and float(%f) values to the respective Ascii format.
• Then set the cursor at x=10, y=10 and print num at this location.
• Set the cursor at x=10, y=30 and print flt at this location.
• We need to call the function SSD1306_UpdateScreen to update the display with the modified content.

Size your buffers to hold the maximum number of characters including sign, decimal point, and the null terminator.

Display Bitmaps

The driver’s SSD1306_DrawBitmap() function renders any image that has been converted to a C byte array.

Step 1 — Convert your image: Use the LVGL image converter tool. Set output format to Binary RGB332, color format to Indexed 1-bit, and output to C array. Download the generated .c file and copy the array into bitmap.h in your project.

Step 2 — Draw and update:

#include "ssd1306.h"
#include "bitmap.h"

SSD1306_Init();
SSD1306_DrawBitmap(0, 0, logo, 128, 64, 1);
SSD1306_UpdateScreen();

#include "ssd1306.h"
#include "bitmap.h"

SSD1306_Init();
SSD1306_DrawBitmap(0, 0, logo, 128, 64, 1);
SSD1306_UpdateScreen();

SSD1306_DrawBitmap(x, y, bitmap, width, height, color) — origin (0,0) is the top-left pixel. Width and height must match your converted image exactly.

Scrolling and Animation

The SSD1306 supports hardware-level scrolling via onboard registers, hence no CPU involvement once triggered. Two directions are available:

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"  // for sprintf
#include "bitmap.h"

int main()
{
  .....
  SSD1306_Init();
  SSD1306_DrawBitmap(0, 0, logo, 128, 64, 1);
  SSD1306_UpdateScreen(); // update screen

  SSD1306_ScrollRight(0x00, 0x07);    // scroll entire screen (Page0 to Page7) right
  HAL_Delay (5000);
  SSD1306_Stopscroll();

  SSD1306_ScrollLeft(0x00, 0x07);    // scroll entire screen (Page0 to Page7) right
  HAL_Delay (5000);
  SSD1306_Stopscroll();
<p style="margin:0;"></p>  while (1) { }
} 

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"  // for sprintf
#include "bitmap.h"

int main()
{
  .....
  SSD1306_Init();
  SSD1306_DrawBitmap(0, 0, logo, 128, 64, 1);
  SSD1306_UpdateScreen(); // update screen

  SSD1306_ScrollRight(0x00, 0x07);    // scroll entire screen (Page0 to Page7) right
  HAL_Delay (5000);
  SSD1306_Stopscroll();

  SSD1306_ScrollLeft(0x00, 0x07);    // scroll entire screen (Page0 to Page7) right
  HAL_Delay (5000);
  SSD1306_Stopscroll();
<p style="margin:0;"></p>  while (1) { }
} 

0x00 to 0x07 selects pages 0–7, covering the full 64-pixel height. Call SSD1306_Stopscroll() before writing new content to the display, otherwise the write will conflict with the active scroll command. Frame-by-frame animation (drawing successive bitmaps in a loop) is demonstrated in the video below.

STM32 SSD1306 OLED I2C: FAQs

The SSD1306 over I2C is one of the most practical display setups in embedded development: two GPIO pins, a small HAL-based driver, and you have a 128×64 OLED capable of text, graphics, and hardware-accelerated scrolling.

The pattern scales directly — the same SSD1306_Init() / SSD1306_UpdateScreen() flow works on STM32F1, F4, and H7 with only the HAL include changed. For projects needing more screen real estate or a graphical UI framework, the SH1106 1.3″ OLED tutorial and the U8G2 graphics library port for STM32 are natural next steps. For character-based output where a full graphics buffer isn’t needed, the I2C LCD1602 tutorial offers a leaner alternative.

Download the complete CubeIDE project below — it includes ssd1306.c/.h, fonts.c/.h, and bitmap.h with the full main.c examples for strings, numbers, bitmaps, and scrolling.

Port U8G2 Library to STM32: SPI, I2C & Software SPI Guide

Interfacing ADXL345 Accelerometer with STM32 via I2C

Interface SH1106 1.3″ OLED with STM32 via I2C — HAL & CubeMX Guide

About the Author

Arun Rawat

Embedded Systems Engineer · Founder, ControllersTech

Arun is an embedded systems engineer with 10+ years of experience in STM32, ESP32, and AVR microcontrollers. He created ControllersTech to share practical tutorials on embedded software, HAL drivers, RTOS, and hardware design — grounded in real industrial automation experience.

About YouTube GitHub Facebook Instagram Shop