Interfacing OLED Display with NodeMCU ESP8266: Displaying Bitmap image on OLED

In this tutorial we will interface OLED Display with NodeMCU ESP8266. NodeMCU is an open source IoT platform that includes firmware which runs on the low cost Wi-Fi enabled ESP8266 Wi-Fi SoC from Espressif Systems. It has GPIO pins for connecting other peripherals and it supports serial communication using SPI, I2C and UART pins. It also has pins for ADC and PWM. We previously interfaced OLED with other microcontroller including the controller of ESP family (ESP32):

• Interfacing SSD1306 OLED Display with Raspberry Pi
• Interfacing SSD1306 OLED Display with Arduino
• Build a Smart Watch by Interfacing OLED Display with Android Phone using Arduino
• Internet Clock using ESP32 and OLED Display

 

In this tutorial we will use SPI protocol to interface Monochrome 7-pin SSD1306 0.96 OLED Display with NodeMCU and will learn to display image on OLED screen with NodeMCU ESP8266.

 

OLED Display

Organic Light Emitting Diode (OLED) is a kind of Light Emitting Diode where a light emitting layer which is made of organic compound emits light when electric current is supplied. This layer is placed between two electrodes. This technology is used in display screens like computers, televisions, smartphones etc. OLED displays have their own light and don’t need any backlight like in LCD, therefore they are power efficient and used with many microcontrollers. One more advantage of using OLED displays over LCD is of displaying large and better quality of graphics on OLEDs. Learn more about OLED Display technology here.

There are various kinds of OLED Displays available in the market. These displays are characterized on the basis of color, number of pins, controller IC and size of the screen. On the basis of color, OLEDs are available in monochrome blue, monochrome white and yellow/blue color. And on the basis of communication, mainly two types of OLEDs are available - 3pin and 7pin. 3 pin OLED can be used in I2C mode of communication and 7 pin OLED can be used either in SPI mode or in I2C mode.

In this tutorial we will use “Monochrome 7-pin SSD1306 0.96” OLED display which is 128 pixels wide and 64 pixels long.  This display can work on both SPI and I2C communication protocols. We will use SPI protocol in this tutorial. SSD1306 IC is present on this OLED which helps to display the pixels on the screen.

 

Components Required

• Monochrome 7-pin SSD1306 0.96” OLED display
• NodeMCU ESP8266
• Micro USB cable
• Breadboard
• Male to Male Jumper wires

 

SPI Pin Connections between NodeMCU and OLED Display

Below is the Circuit Diagram for connecting of 7 pin OLED Display with NodeMCU to communicate using SPI serial communication protocol.

Below table shows the connections between OLED Display and NodeMCU ESP8266. GND pin goes to NodeMCU GND, VDD pin can be connected to 3.3V or 5V, SCK is the clock pin on OLED Display which is connected to D5 of NodeMCU for SPI clock. The SDA pin which is MOSI pin on OLED of SPI interface goes to D7 of NodeMCU. The RESET pin goes to D3. DC, the data command pin is connected to D2 of NodeMCU. The last pin is CS goes to D8, chip select of NodeMCU.

No.	Oled Display	NodeMCU
1	GND	GND
2	VDD	3.3V
3	SCK	D5
4	MOSI (SPI) or SDA (I2C)	D7
5	RESET	D3
6	DC	D2
7	CS	D8

 

Here we will use “Adafruit _SSD1306.h” and “Adafruit_GFX.h” library for interfacing OLED with NodeMCU. Open Arduino IDE and install the latest version from Arduino IDE (Sketch > Include Library > Manage Libraries or Ctrl+Shift_I).

 

Since pixel size of our OLED display id 128x64, therefore we have to do a change in header file of Adafruit_SSD1306. Open the Arduino libraries, go to Adafruit_SSD1306 and open its header file (Adafruit _SSD1306.h). Comment out the line “#define SSD1306_128_32” and uncomment the line “#define SSD1306_128_64” as shown in the below image and then save the file. By default this library comes with “#define SSD1306_128_32”.

 

Finally change the pin numbers in “ssd1306_128x64_spi” Adafruit SSD1306 example according to the table shown abve. Now when you run the sketch after making proper connection of OLED Display with NodeMCU you will see Adafruit’s logo on OLED display which is by default saved in the library. After Adafruit logo it displays many other graphics like lines, rectangles, triangle, circles, strings, numbers, animations and bitmap. Here In this tutorial we will learn how to display any image on OLED with NodeMCU ESP8266.

 

Programming NodeMCU for interfacing OLED

As always complete code is provided at the end, here we have explained the code in detail.

Start the code by importing necessary libraries. Since we are using SPI protocol therefore we will import “SPI.h” library and also import “Adafruit_GFX.h” and “Adafruit_SSD1306.h” for OLED Display.

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

 

Our OLED size is 128x64 so we are setting screen width and height as 128 and 64 respectively. So  define the variables for OLED pins connected to NodeMCU for SPI communication.

#define SCREEN_WIDTH 128 // OLED display width, in pixels
#define SCREEN_HEIGHT 64 // OLED display height, in pixels

// Declaration for SSD1306 display connected using software SPI (default case):
#define OLED_MOSI   D7
#define OLED_CLK   D5
#define OLED_DC    D2
#define OLED_CS    D8
#define OLED_RESET D3

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT,
  OLED_MOSI, OLED_CLK, OLED_DC, OLED_RESET, OLED_CS);

 

Initialize of the OLED display by using SSD1306_SWITCHCAPVCC to generate 3.3V internally to initialize the display.

if(!display.begin(SSD1306_SWITCHCAPVCC))
{
   Serial.println(F("SSD1306 allocation failed"));
   for(;;); // Don't proceed, loop forever
  }

 

The display of OLED screen is cleared before displaying anything by calling function display.clearDisplay(). We set the font size to 2 by calling function setTextSize(font-size), and set the text color and cursor position by using setTextColor and setCursor function. Display.display() command is used to transfer data to the internal memory of SSD1306 controller. After the transfer, pixel shows up on the screen. Now we can start scrolling the text in various ways by calling display.startscrollright(x-pos,y-pos) and display.startscrollleft(x-pos,y-pos) for the time given in delay function. Scrolling of text can be stopped using function display.stopscroll().

void testscrolltext(void) {
  display.clearDisplay(); // clear the display screen of the OLED
  display.setTextSize(2); // Draw 2X-scale text
  display.setTextColor(WHITE);
  display.setCursor(0, 0);
  display.println(F("CIRCUIT"));
  display.println(F("DIGEST"));
  display.display();      // Show initial text
  delay(100);

  // Scroll in various directions, pausing in-between:
  display.startscrollright(0x00, 0x0F);
  delay(2000);
  display.stopscroll();
  delay(1000);
  display.startscrollleft(0x00, 0x0F);
  delay(2000);
  display.stopscroll();
  delay(1000);
  display.startscrolldiagright(0x00, 0x07);
  delay(2000);
  display.startscrolldiagleft(0x00, 0x07);
  delay(2000);
  display.stopscroll();
  delay(1000);
}

 

We call display.drawBitmap() function which takes 6 parameters (x-coordinate, y-coordinate, bitmap array, width, height and color) to draw the image on OLED. Since our display size is 128x64 therefore we set the width and height as 128 and 64 respectively. Here the bitmap array contains the pixel information to draw the pixel on screen to create the image. This bitmap array can be generated online which is explained below or there are many software available to convert image into bitmap array.

const unsigned char myBitmap [] PROGMEM = {
  0xff, 0xff, 0xff, 0xe0, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xff, 0xc0, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf7, 0xc0, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xc7, 0x80, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x0f, 0x01, 0xc0, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xfe, 0x0f, 0x03, 0xff, 0xc0, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xf8, 0x1e, 0x03, 0x3f, 0xf8, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xf0, 0x3e, 0x03, 0x3f, 0xfc, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xe0, 0x3c, 0x03, 0x7f, 0xfe, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xc0, 0x7c, 0x03, 0xf0, 0x3f, 0x83, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0x80, 0x78, 0x00, 0xc0, 0x0f, 0xc1, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0x00, 0xf8, 0x00, 0x00, 0x07, 0xe0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xfe, 0x01, 0xf0, 0x00, 0x00, 0x03, 0xf8, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xfc, 0x01, 0xf0, 0x00, 0x00, 0x00, 0xfc, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xfc, 0x03, 0xe0, 0x00, 0x0f, 0x00, 0x7e, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xf8, 0x07, 0xc0, 0x3f, 0xff, 0x80, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xc0, 0x7f, 0xf9, 0x80, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x80, 0xff, 0xf9, 0x80, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x80, 0xff, 0xff, 0x80, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x01, 0xf0, 0x1f, 0x80, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xc0, 0x00, 0x03, 0xe0, 0x06, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xc0, 0x00, 0x03, 0xc0, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xc0, 0x00, 0x07, 0xc0, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x07, 0x80, 0x00, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x0f, 0x80, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x0f, 0x00, 0x80, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x1e, 0x01, 0xe0, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x1e, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x3c, 0x03, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x7c, 0x03, 0x3f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf8, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf8, 0x01, 0xe0, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf0, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x00, 0x00, 0x00, 0xc0, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x01, 0xf0, 0x00, 0x00, 0x00, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x03, 0xb0, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x03, 0x18, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0x80, 0x00, 0x03, 0xbc, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xc0, 0x00, 0x01, 0xfe, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xc0, 0x00, 0x00, 0xff, 0xff, 0x80, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xf0, 0x00, 0x1f, 0xff, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xfe, 0x00, 0x07, 0xfc, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x80, 0x03, 0xf0, 0x00, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xe0, 0x01, 0xc0, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf8, 0x00, 0x00, 0x00, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xf8, 0x03, 0xff, 0xc0, 0x00, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xf8, 0x00, 0xff, 0xe0, 0x00, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xfc, 0x00, 0x3f, 0xe0, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xfe, 0x00, 0x0e, 0x30, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0x00, 0x07, 0x70, 0x00, 0xff, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0x80, 0x03, 0xe0, 0x1b, 0xfc, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xc0, 0x01, 0xc0, 0x7f, 0xf0, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xe0, 0x00, 0x00, 0x7f, 0xc0, 0x07, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xf0, 0x00, 0x00, 0x67, 0x00, 0x0f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xf8, 0x00, 0x00, 0x66, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xfe, 0x00, 0x00, 0x7e, 0x00, 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0x00, 0x00, 0x3c, 0x01, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xc0, 0x00, 0x00, 0x03, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xf0, 0x00, 0x00, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xfe, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
  0xff, 0xff, 0xff, 0xf8, 0x1f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
};

  display.drawBitmap(35, 0,  myBitmap, 128, 64, BLACK, WHITE);
  display.display();

 

Convert image into Bitmap Values

Online Bitmap can be generated from http://javl.github.io/image2cpp/. Upload the image file you want to display on the OLED and set size as 128x64. A preview image will be shown and then bitmap array will be generated.

Below screenshots shows the process to generate the bitmap value of any image.

 

Finally upload the complete code into NodeMCU ESP8266 and you will see image displaying on OLED Screen. Here we are displaying CircuitDigest logo on OLED display.