Interfacing SSD1306 OLED display with Arduino, ESP32 and ESP8266

Learn how to connect an OLED display with few frequently used development boards like Arduino, ESP32 and ESP8266[NodeMCU, Wemos D1]

In this detailed tutorial learn what is OLED display, How an OLED display works with SSD1306 driver and finally how to interface an SSD1306 OLED display with Arduino, ESP32 and ESP8266 and display the output text, numbers, scrolling data, ASCII, and even images from a microcontroller to the OLED display.

What is OLED display ?

The Acronym of OLED is Organic Light Emitting Diode, You may get a doubt about organic. Yes, even I thought of any  living organic matter, But later found that the OLED composed of sheet organic materials such as Coal. these sheets are placed between two conductors and emits light when electricity is applied to them.

Till the introduction of OLED displays you might have used the older LCD display modules which made your projects projects look like old and retro. But later OLED displays came into action to make the change.

OLED displays have multiple advantages over the LCD displays, they look super cool, very thin nearly the thickness of paper, consumes lower power and produce a brighter and sharp contrast image when compared with LCD displays.

One of the advantages of OLED screens over LCD screens is that they do not require a backlight or filters.

This makes OLED screens are more efficient in terms of energy , more easy to manufacture and more thin . They can also be flexible and transparent.

How an OLED display works? Role of SSD1306 OLED driver

OLED display requires a controller or a driver to display data or information on them, they are useless with out a driver.

oled display module i2c

Generally all the OLED displays for made for Arduino comes with driver packed in the module it self, they can be directly connected to the microcontroller, the driver with in the OLED display works as the communication system between the microcontroller board and the OLED display through I2C or SPI protocols.

SPI communication is faster than I2C communication protocol but SPI requires more number of I/O pins for connection when compared with I2C which requires only 2 for data transfer and we can connect upto 128 devices, so its up to your requirement whether to opt for SPI or I2C.

SSD1306 driver

The OLED display which we are interfacing with Arduino in this article is integrated with SSD1306 Driver which is well known and powerful OLED CMOS controller. There are many other drivers which has their own level of features. Since SSD1306 is versatile, manufacturing different color, size OLED displays are possible. for example we frequently find OLEDs with sizes 128×32, 128×64, with Blue color OLEDs, White color OLEDs and Dual Color OLEDs.

To know the detailed technical specifications read the official datasheet: SSD1306 Datasheet PDF

Power supply requirements for SSD1306 OLED display module

The Operating voltage of the SSD1306 driver is from 1.65V to 3.3V. with the help of a voltage regulator which converts input voltage between 1.8V and 6V to stable 3.3V output voltage.

On the other hand the OLED display requires input voltage between 7V to 15V. which is not in the range of the driver. So there are internal voltage doublers and Charge pump circuitry which helps to obtain higher voltages from the supplied voltage. Which makes these OLED displays to work with any microcontrollers like Arduino, NodeMCU, ESP32, etc. which supply 3.3V or 5V.

OLED displays works with out a backlight sheet present in the LCD display as OLED produce their light in the pixel level. This is the reason why they have high contrast, deeper black as the pixel is turned off which doesn’t produce any light. This makes the OLED to consume lower amount of current, as only on pixels consume current. On a average OLED display consumes only 20mA current.

How data displayed on Graphical display using OLED memory mapping

As we read from the above, SSD1306 is the heart of the OLED display module

To display the data on the screen, the SSD1306 controller has a bit mapped static RAM or Graphic RAM called GDDRAM ( Graphic Display Data RAM ) with capacity to store 1 KB of data.

This 1KB equates to 1,024 bytes or 8,192 bits that are distributed on the screen in a matrix of rows (pages) and columns (segments). In total there are 8 pages (rows) and each page has 128 segments (columns) which, in turn, each segment stores 1 byte.

oled display data mapping with zoomed pixels


Each bit represents a pixel on the OLED screen and through programming can be turned on or off to display any information.

But don’t be scared, we won’t have to work at the bit level. That is what the Arduino and ESP8266 libraries take care of . But before we dive into programming, let’s see the pinning of OLED screens.

Pinout Diagram of OLED display module

OLED display with I2C protocol has only 4 pins as shown in the below pinout diagram

oled display pinout diagramFrom the above image you can observe the first 2 pins the VCC and GND are for power supply from 3.3V to 5V and Ground respectively. and other 2 pins SCL and SDA are for Serial Clock and Serial Data pins for I2C respectively.

Circuit Diagram interfacing OLED display with Arduino UNO

Connect the OLED display module with Arduino as shown in the below schematic Diagram.

Circuit Diagram interfacing OLED display with ArduinoFrom the above connection diagram you can notice we connected OLED display VCC and GND to 5V and GND respectively and SCL and SDA to A5 and A4 of Arduino respectively. That’s it for connection, Upload the code to work accordingly.

As there are few versions of Arduino’s the I2C pins table is shown below

Arduino Version SDA SCL
Arduino Pro Mini A4 A5
Arduino MEGA 20 21
Arduino DUE 20 21
Arduino Leonardo 2 3
Arduino Yun 2 3
Arduino Nano A4 A5
Arduino MKR1000 11 12

Circuit Diagram interfacing OLED display with ESP8266

Connect the OLED display module with ESP8266 NodeMCU as shown in the below schematic Diagram.

Circuit Diagram interfacing OLED display with ESP8266

From the above connection diagram you can notice we connected OLED display VCC and GND to 3.3V and GND respectively and SCL and SDA to D1 and D2 of ESP8266 nodeMCU respectively. That’s it for connection, Upload the code to work accordingly.

Circuit Diagram interfacing OLED display with ESP32

Connect the OLED display module with ESP32 Wifi and Bluetooth microcontroller as shown in the below schematic Diagram.

Circuit Diagram interfacing OLED display with ESP32

From the above connection diagram you can notice we connected OLED display VCC and GND to 3.3V and GND respectively and SCL and SDA to D22 and D21 of ESP32 WiFi and Bluetooth microcontroller respectively. That’s it for connection, Upload the code to work accordingly.

Uploading the code through Arduino IDE

After connecting next step is to write the code and upload it to microcontroller using Arduino IDE, So here with OLED display module we need to install few libraries which are required for SSD1306 driver.

Required Libraries: download link

  • Adafruit SSD1306
  • Adafruit GFX Library

You can install these libraries from the Arduino IDE itself by simply following the below steps:

-> from the menu bar click on Sketch -> Manage Libraries -> Search for required library in search box -> choose and click on install.

Source code

Here we are showing the example code to display

  • Normal Text
  • Numbers
  • Inverted Text and Numbers
  • ASCII characters and symbols
  • Scrolling Text Horizontally & Vertically
  • Scrolling part of the display
  • Displaying images.

Printing simple text:

How code works:

The code starts by including the required libraries,

The above line is a constructor which accepts the screen resolution or size and -1 to indicate no pins are allocated to reset the display.

the above line initialize the OLED display taking two parameters, SSD1306_SWITCHCAPVCC to turn the internal pump circuitry ON  and another 0x3C is the I2C address of the OLED display, if you get any error regarding this address if you are using any cheap OLED display find the I2C address with I2C Scanner here – link.

display.setTextSize(1);   –> Font size of text

display.setTextColor(WHITE); –> Color of the text, WHITE for bright text dark background, BLACK for dark text and bright background.

display.setCursor(0,28);  –> coordinates (x,y), increasing x moves cursor horizontal, Increasing y moves cursor vertical.

display.display(); –> Transfer the screen buffer from the microcontroller to SSD1306 driver in bulk.


Printing Numbers:

All the other main code snippets remain same, we are just showing the code to display numbers.

Inverted Text and Numbers

Here inverted indicates the inverting of text color with background color.

display.setTextColor(BLACK, WHITE); -> parameters (fontcolor, backgroundcolor)

ASCII characters and symbols

here in this example display.write(x); prints the binary data, while the print and println prints the human readable ASCII, here we are passing the parameter 2 for a smiley , You can refer the code page 437 for all the ASCII binary values.

After uploading the code the OLED display shows the below output

Displaying ASCII Symbols smiley symbol

Scrolling screen Horizontally & Vertically

startscrollright(), startscrollleft(), startscrolldiagright() & startscrolldiagleft() functions will scroll the screen from current position to the specified direction, these functions take two parameter (START page, STOP page), As we learnt from the OLED mapping topic about eight pages from 0 to 7,

display.startscrollright(0x00, 0x07); -> scrolling to right 0 to 7 pages means all the rows scroll to right

display.startscrolldiagright(0x00, 0x07); scrolling to right in diagonally from current position to right from bottom to top.

display.stopscroll();-> Stops the display from scrolling

Note: the parameters are in hexadecimal.

To scroll specific page from 0 to 7 use the below code

Drawing Shapes

learn how to draw circle, rectangle, triangle on OLED display using Arduino, ESP32, ESP 8266 as shown in the below output images

drawing on oled display

Displaying Bitmap images on OLED display connected with Arduino, ESP8266, ESP32

For displaying bitmap images we need to convert a bitmap image to byte array, And remember as our OLED display screen size is 128X64 the image should in the same aspect ratio to get the image in better aspect ratio.

There are few online and offline tools to generate the byte arrays one of the most popular online tools is image2cpp which is easy and has many features like centering, scaling, stretching, rescaling the image and preview the output.

You can also use an offline software LCD assistant program which works without internet.

Upload the image twerk some setting to get best preview and generate the code for Arduino IDE and copy paste it on our code.

After uploading the code the OLED prints the images as shown in the below output image

displaying bitmap image on oled display using arduino


CircuitSchools Staff

We at CircuitSchools publish on basics of electronics and electric components and everything related to evolution of electrical technology with complete analysis of development boards and modules along with latest projects with innovative ideas.

Related Articles

Back to top button