How to 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 LCD2004 LCD with STM32

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

Components and OLED Display Overview

Before we start configuring CubeMX or writing any code, it’s important to understand the components used in this project — especially the SSD1306 OLED display. Knowing the display’s features and how it communicates will make it much easier to work with it in your STM32 projects.

What is the SSD1306 OLED Display?

The SSD1306 is a popular display driver IC that powers many 0.96-inch 128×64 pixel OLED modules. These modules are commonly used in embedded systems and hobby electronics due to their high contrast, wide viewing angles, and low power consumption.

Unlike traditional LCDs, OLED (Organic Light Emitting Diode) displays do not require a backlight. Each pixel emits its own light, resulting in deep blacks and clear text, even in low-light environments.

Most SSD1306 modules support both I2C and SPI communication protocols. In this tutorial, we’ll use the I2C version, which requires fewer pins and is easier to set up with STM32.

These displays are perfect for adding simple user interfaces, sensor dashboards, or text output to embedded projects. You can display strings, numbers, graphics, icons, and even small animations.

Key Features and Specifications

Here are some of the most important features of the SSD1306 OLED module:

This compact module fits easily on breadboards and development boards, making it excellent for both prototyping and final embedded designs.

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.

Circuit Diagram and Connections

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.

STM32CubeMX Configuration for I2C

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

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.

Writing the SSD1306 Driver with HAL

Open the ssd1306.c file and update the I2C handler to match your STM32 board setup. Configuring the correct I2C peripheral is crucial for reliable communication with the SSD1306 OLED display.

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

In this example, we use I2C1 on the STM32. Replace hi2c1 with the handler corresponding to the I2C interface you have enabled in STM32CubeMX. This ensures the microcontroller sends data correctly to the OLED display.

Tip: Always verify your I2C address and wiring before running the code. SSD1306 modules typically use 0x3C or 0x3D as the default I2C address.

Also configure the display resolution in the ssd1306.h file.

/* SSD1306 width in pixels */
#ifndef SSD1306_WIDTH
#define SSD1306_WIDTH            128
#endif
/* SSD1306 LCD height in pixels */
#ifndef SSD1306_HEIGHT
#define SSD1306_HEIGHT           64
#endif

/* SSD1306 width in pixels */
#ifndef SSD1306_WIDTH
#define SSD1306_WIDTH            128
#endif
/* SSD1306 LCD height in pixels */
#ifndef SSD1306_HEIGHT
#define SSD1306_HEIGHT           64
#endif

You can see the functions available in the functions tab under ssd1306.c and in the ssd1306.h file.

Print simple strings on 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) { }
}  

• Here we will first initialise the display in the main function.
• Then set the cursor at x=10, y=10 and print “HELLO” at this location.
• Set the cursor at x=10, y=30 and print “WORLD !!” at this location.
• We need to call the function SSD1306_UpdateScreen to update the display with the modified content.

Below is the image showing the output of the above code.

Display Numbers on SSD1306

Any display does not support printing the numbers directly on it. Instead we need to change the number into the equivalent Ascii characters and then print it.

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) { }
} 

• Here we will first initialise the display in the main function.
• Then define the character buffers to store the converted integer and float values.
• 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.

Below is the image showing the output of the above code.

Display Bitmaps on SSD1306

We can draw a bitmap image anywhere on the display. We just need to convert the bitmap image to c array format. This tool can do that.

Make sure to choose the configuration as shown below.

Once you click Convert, the c file containing the image array will download. We will copy the array to our project.

#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<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<p style="margin:0;"></p>  while (1) { }
} 

• Here we will first initialise the display in the main function.
• Then draw the bitmap defined in the bitmap.h file.
• The bitmap start position is set to x=0,y=0.
• The size is 128pixels x 64pixels.
• We need to call the function SSD1306_UpdateScreen to update the display with the modified content.

Below is the image showing the output of the above code.

Scrolling and Animation on SSD1306

The SSD1306 has support for scrolling at hardware level. There are registers in the SSD1306 IC which enable the display to scroll in different directions.

The following are the functions available to do so.

#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) { }
} 

In the code above, we are scrolling the entire screen in the right direction for 5 seconds, and then in the left direction for another 5 seconds. The screen contains the bitmap on it and therefore we will see the bitmap scrolling.

The Animation part is explained in the video shown below. Please check out the video to see the complete working.

Conclusion

In this tutorial, we successfully interfaced an OLED display with an STM32 microcontroller using the I2C protocol. We covered the initialization process, command/data handling, and demonstrated how to display text and graphics on the screen. The OLED provides a compact and power-efficient way to add a user interface to embedded projects, making it ideal for IoT devices, portable gadgets, and various real-time applications.

By understanding the communication flow and display functions, you can now expand this project further—such as creating custom animations, menus, or integrating sensor data visualization. This not only enhances the usability of your STM32 projects but also gives them a more professional and interactive touch.

Interfacing ADXL345 Accelerometer with STM32 via I2C – Complete Tutorial with Code

How to use 4×4 keypad with STM32

LCD 20X4 using I2C with STM32

How to interface MPU6050 (GY-521) with STM32

Interface TFT display with STM32

Interface 16×2 LCD with STM32 (No I2C) — 4-bit Guide

ST7735 1.8″ TFT Display with STM32

Custom characters in LCD 1602 || STM32

1 2 3 4 5 Next »