Interface SSD1306 OLED Display with STM32 Using I2C

The SSD1306 OLED is one of the most common displays in embedded projects. It is small, it has high contrast, and it draws very little current. The popular 0.96 inch module has a resolution of 128×64 pixels, and it can communicate over I2C or SPI.

This tutorial shows how to connect an SSD1306 OLED to an STM32 over I2C. The I2C peripheral is configured in STM32CubeMX, the code is written with the HAL library, and a small driver draws text, numbers, bitmaps, and scrolling animations on the screen. The example runs on an STM32F103C8T6 (BluePill), and the same steps work on the F4, H7, and most other STM32 series with only the HAL header changed.

The project uses the 0.96 inch SSD1306 OLED module and the STM32F103C8T6 BluePill board. Other displays are covered in the STM32 display and GUI tutorials, and links to the most relevant ones are listed near the end of this article.

SSD1306 OLED Display Overview and Specifications

The SSD1306 is a driver IC for monochrome OLED panels. It is used in the 0.96 inch 128×64 modules that appear in many embedded and IoT projects.

OLED pixels emit their own light, so the display needs no backlight. This gives deep blacks, high contrast, and a wide viewing angle even at low supply current. Most breakout modules support both I2C and SPI, and this tutorial uses the I2C version.

The main specifications are listed here.

• Display type: Monochrome OLED.
• Driver IC: SSD1306.
• Resolution: 128 × 64 pixels.
• Operating voltage: 3.3 V or 5 V, depending on the module.
• Communication: I2C in this tutorial, with SPI available on some modules.
• Default I2C address: 0x3C, or 0x3D on modules where the address pin is pulled high.
• Viewing angle: More than 160 degrees.
• Backlight: None, because the pixels emit light directly.

SSD1306 I2C Interface Advantages

I2C is a two-wire serial protocol that uses a data line (SDA) and a clock line (SCL). Most STM32 devices include several I2C peripherals, which makes the protocol a good fit for displays and sensors.

Using I2C with the SSD1306 has several benefits.

• Fewer pins: Only two signal lines are needed, so more pins stay free for other peripherals.
• HAL support: CubeMX configures the I2C peripheral, and the HAL library provides the transfer functions.
• Shared bus: Several I2C devices, such as sensors and displays, can share the same two lines as long as each one has a different address.
• Simple wiring: The module needs only four connections, which reduces mistakes on a breadboard.

For these reasons, I2C is the most common and beginner-friendly way to connect the SSD1306 to an STM32.

Wiring the SSD1306 OLED to STM32

The wiring is short because the module needs only power, ground, and the two I2C lines.

The connections are as follows.

• VCC: Connect this pin to the 3.3 V pin of the STM32 board to power the display.
• GND: Connect this pin to a GND pin of the STM32 board.
• SCL: Connect this pin to the I2C clock pin of the STM32, which is PB6 for I2C1 on the BluePill.
• SDA: Connect this pin to the I2C data pin of the STM32, which is PB7 for I2C1 on the BluePill.

SSD1306 modules work from either 3.3 V or 5 V, depending on the board. Many modules have an onboard regulator, which lets them run from 5 V while the display itself runs at 3.3 V. The safest option is to power the module from 3.3 V when the module allows it.

If the module has to be powered from 5 V, check whether its pull-up resistors are connected to VCC, because the I2C lines would then also rise to 5 V. In that case, the STM32 pins used for I2C must be 5 V tolerant, which is true for many pins on the F1 and F4 series. A level shifter is the alternative for pins that are not 5 V tolerant. Most modules already include pull-up resistors, but a bare module on a custom board needs external pull-ups, typically 4.7 kΩ to 3.3 V.

STM32 CubeMX Setup for SSD1306 I2C

After the wiring is complete, the I2C peripheral is configured in STM32CubeMX.

Clock Configuration

The board uses its 8 MHz external crystal (HSE), and the PLL raises the system clock to the 72 MHz maximum of the STM32F103.

I2C Fast Mode at 400 kHz

The project uses I2C1.

• Set the I2C speed mode to Fast Mode, which sets the clock to 400 kHz. A full screen update sends 1024 bytes, so the higher speed gives noticeably faster refreshes and smoother animations.
• CubeMX assigns the pins automatically. PB6 becomes SCL, and PB7 becomes SDA.

SSD1306 Driver Setup for STM32 HAL

The project uses a small driver that consists of four files: ssd1306.c, ssd1306.h, fonts.c, and fonts.h. Copy the two .c files into the Src folder and the two .h files into the Inc folder of your CubeIDE project. In Keil, the files must also be added to the project group, because copying them into the folder is not enough.

Open ssd1306.c and make sure the I2C handle matches the one that CubeMX generated.

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

extern I2C_HandleTypeDef hi2c1;
#define SSD1306_I2C &hi2c1

If CubeMX used I2C2 or I2C3, change hi2c1 to hi2c2 or hi2c3. A linker error that mentions an undefined reference to hi2c1 means that I2C1 is not enabled in CubeMX or that the handle name does not match.

Next, check the resolution values in ssd1306.h.

#define SSD1306_WIDTH   128
#define SSD1306_HEIGHT   64

#define SSD1306_WIDTH   128
#define SSD1306_HEIGHT   64

The driver uses the I2C address 0x3C by default. If your module uses 0x3D, change the address define in the driver. HAL functions expect the 7-bit address shifted left by one bit, so depending on the driver version, the same address may appear in the code as 0x78.

The header ssd1306.h also includes the HAL header for the F1 series. On other families, change it to the matching file, for example stm32f4xx_hal.h for the F4 series.

Display Text on SSD1306 OLED with STM32

The following code prints two lines of text.

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

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

  SSD1306_Init();                                  // initialize the display
  SSD1306_GotoXY(10, 10);                          // move the cursor to x = 10, y = 10
  SSD1306_Puts("HELLO", &Font_11x18, 1);           // write the first line
  SSD1306_GotoXY(10, 30);
  SSD1306_Puts("WORLD !!", &Font_11x18, 1);        // write the second line
  SSD1306_UpdateScreen();                          // send the buffer to the display

  while (1)
  {
  }
}

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

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

  SSD1306_Init();                                  // initialize the display
  SSD1306_GotoXY(10, 10);                          // move the cursor to x = 10, y = 10
  SSD1306_Puts("HELLO", &Font_11x18, 1);           // write the first line
  SSD1306_GotoXY(10, 30);
  SSD1306_Puts("WORLD !!", &Font_11x18, 1);        // write the second line
  SSD1306_UpdateScreen();                          // send the buffer to the display

  while (1)
  {
  }
}

The functions work as follows.

• SSD1306_Init() sends the complete initialization sequence to the display.
• SSD1306_GotoXY(x, y) sets the cursor position in pixels.
• SSD1306_Puts() writes the text into an internal frame buffer.
• SSD1306_UpdateScreen() sends the frame buffer to the display. Nothing appears on the screen until this function is called.

Display Numbers and Floats on the OLED

The display can only draw characters, so a number has to be converted to text first. The sprintf function does this conversion.

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

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

  int num = 123456;
  float flt = 123.45f;
  char bufnum[16];
  char bufflt[16];

  SSD1306_Init();

  sprintf(bufnum, "%d", num);
  sprintf(bufflt, "%.2f", flt);

  SSD1306_GotoXY(10, 10);
  SSD1306_Puts(bufnum, &Font_11x18, 1);
  SSD1306_GotoXY(10, 30);
  SSD1306_Puts(bufflt, &Font_11x18, 1);
  SSD1306_UpdateScreen();

  while (1)
  {
  }
}

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

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

  int num = 123456;
  float flt = 123.45f;
  char bufnum[16];
  char bufflt[16];

  SSD1306_Init();

  sprintf(bufnum, "%d", num);
  sprintf(bufflt, "%.2f", flt);

  SSD1306_GotoXY(10, 10);
  SSD1306_Puts(bufnum, &Font_11x18, 1);
  SSD1306_GotoXY(10, 30);
  SSD1306_Puts(bufflt, &Font_11x18, 1);
  SSD1306_UpdateScreen();

  while (1)
  {
  }
}

The format %d converts an integer, and %.2f converts a float with two digits after the decimal point. Each buffer must be large enough to hold all characters, including the sign, the decimal point, and the terminating null character. Printing a float with sprintf also requires float support in the linker settings of the project, which some toolchains disable by default.

The same method works for live sensor data. Convert the reading with sprintf, clear the old text with SSD1306_Clear(), and call SSD1306_UpdateScreen() after each change.

Display Bitmap Images on the OLED

The function SSD1306_DrawBitmap() draws any image that has been converted into a C byte array.

The conversion takes two steps.

1. Open the LVGL image converter and load the image. Choose Binary RGB332 as the output format, Indexed 1-bit as the color format, and C array as the output.
2. Download the generated .c file, and copy the array into a header file named bitmap.h in your project.

The bitmap is then drawn and sent to the display.

#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();

The arguments of SSD1306_DrawBitmap(x, y, bitmap, width, height, color) are the top-left position, the array, the size of the image, and the pixel color. The origin (0, 0) is the top-left pixel of the screen. The width and height must match the converted image exactly, or the picture will look distorted.

SSD1306 Scrolling and Animation with STM32

The SSD1306 can scroll the screen content in hardware. After the scroll command is sent, the display handles the movement by itself and the CPU is not involved.

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"
#include "bitmap.h"

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

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

  SSD1306_ScrollRight(0x00, 0x07);   // scroll pages 0 to 7 to the right
  HAL_Delay(5000);
  SSD1306_Stopscroll();

  SSD1306_ScrollLeft(0x00, 0x07);    // scroll pages 0 to 7 to the left
  HAL_Delay(5000);
  SSD1306_Stopscroll();

  while (1)
  {
  }
}

#include "ssd1306.h"
#include "fonts.h"
#include "stdio.h"
#include "bitmap.h"

int main(void)
{
  /* HAL and peripheral initialization generated by CubeMX */

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

  SSD1306_ScrollRight(0x00, 0x07);   // scroll pages 0 to 7 to the right
  HAL_Delay(5000);
  SSD1306_Stopscroll();

  SSD1306_ScrollLeft(0x00, 0x07);    // scroll pages 0 to 7 to the left
  HAL_Delay(5000);
  SSD1306_Stopscroll();

  while (1)
  {
  }
}

The values 0x00 and 0x07 select pages 0 to 7, which cover the full 64 pixel height of the screen. The scroll must be stopped with SSD1306_Stopscroll() before new content is written, because a write during an active scroll conflicts with the scroll command.

Frame-by-frame animation works differently. The program draws a series of bitmaps one after another in a loop and calls SSD1306_UpdateScreen() after each frame. This method is shown in the video.

SSD1306 OLED Not Working: Troubleshooting

Most problems come from a small number of causes. The following checks solve the majority of reports.

• The wiring must match the pins chosen in CubeMX. SDA and SCL are easy to swap, and a swapped pair gives a blank screen with no error message.
• The I2C address must match the module. Some modules use 0x3D instead of 0x3C, and the HAL functions expect the address in its shifted form.
• The handle name in ssd1306.c must match the I2C peripheral that is enabled in CubeMX.
• SSD1306_UpdateScreen() must be called after every change to the frame buffer. The display stays blank without it.
• The module needs pull-up resistors on SDA and SCL. Most modules include them, but a bare display on a custom board does not.
• The project must include the HAL header of the correct STM32 family. A build error such as stm32f1xx_hal.h: No such file or directory means the header in ssd1306.h and fonts.h belongs to a different family.
• A column of stray pixels at the right edge can mean that the module uses an SH1106 controller instead of an SSD1306. The SH1106 has 132 columns and needs a slightly different driver, which is covered in the SH1106 OLED tutorial.

If the display still stays blank, a short scan of the I2C bus shows whether the STM32 can reach the module at all.

for (uint8_t addr = 1; addr < 128; addr++)
{
  if (HAL_I2C_IsDeviceReady(&hi2c1, addr << 1, 1, 10) == HAL_OK)
  {
    // a device answered at this 7-bit address, for example 0x3C
  }
}

for (uint8_t addr = 1; addr < 128; addr++)
{
  if (HAL_I2C_IsDeviceReady(&hi2c1, addr << 1, 1, 10) == HAL_OK)
  {
    // a device answered at this 7-bit address, for example 0x3C
  }
}

A breakpoint inside the if block shows the address of every device that responds.

STM32 SSD1306 OLED Summary and Next Steps

This tutorial showed how to connect a 0.96 inch SSD1306 OLED to an STM32 over I2C. It covered the wiring, the CubeMX configuration with I2C Fast Mode, and the driver setup, and it then displayed text, numbers, bitmaps, and hardware scrolling on the screen.

The pattern is the same on every STM32 family. The program initializes the display, writes into the frame buffer, and sends the buffer to the screen with SSD1306_UpdateScreen(). Only the HAL header and the I2C handle change between boards.

For a larger screen or a richer graphics library, the SH1106 tutorial and the U8G2 port are the natural next steps. For text-only output, the I2C LCD1602 tutorial is a simpler option.

Browse More STM32 Display Tutorials

ST7735 1.8″ TFT Display with STM32

LVGL on STM32 || PART 2

TouchGFX #3. Sending data to UI || MVP

LVGL on STM32 || PART7 || Load LVGL from Ext Flash

Interface I2C-LCD1602 (AIP31068) with STM32

How to Cascade Dot Matrix Displays with STM32 – Step-by-Step SPI Guide

1 2 3 4 5 6 Next »

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