ESP32 OLED Display Setup

I’ve recently started working on several projects using the ESP32 which has become one of my favorite “maker” class boards. Although I probably still prefer the STM32F4s for hard number crunching, the ESP32 has proved incredibly versatile for a host of WiFi applications.

One particularly interesting ESP32 module features an integrated OLED display and it can be found from multiple manufactures and vendors.

Example AliExpress Listing

Example Amazon Listing

I now have a few of these and I quickly discovered there’s very little up-to-date information about how to get these to work. After several hours of work, I thought I’d post my results.

Prerequisites:

• Install the arduino-esp32 Arduino Core following their latest instructions
• Install the Adafruit_SSD1306 library by placing it in your Arduino Libraries path
• Install the Adafruit-GFX-Library by placing it in your Arduino Libraries path

So far I haven’t found any issues by using just the vanilla “ESP32 Dev Module” profile:

The particular boards I have a 128x64 character display, unfortunately this involves modifying the Adafruit_SSD1306.h file from the SSD1306 library:

//   #define SSD1306_128_64
     #define SSD1306_128_32
//   #define SSD1306_96_16

becomes:

     #define SSD1306_128_64   
//   #define SSD1306_128_32
//   #define SSD1306_96_16

While we’re in the SSD1306 library, change Adafruit_SSD1306.cpp begin function

// I2C Init    
Wire.begin();

becomes:

// I2C Init    
Wire.begin(5,4); //SDA, SCL

Next we should open the Adafruit example, ssd1306_128x64_i2c.ino:

First we need to not use the i2c pin as a reset pin:

#define OLED_RESET 4
Adafruit_SSD1306 display(OLED_RESET);

becomes:

#define OLED_RESET 0
Adafruit_SSD1306 display(OLED_RESET);

NOTE: I have not identified which pin if any corresponds to the SSD1306 reset pin. Pin 0 was not in use so there was no harm in using it. If you want full functionality you will need to locate the SSD1306 reset pin.

Finally,

void setup()   {                
  Serial.begin(9600);
  display.begin(SSD1306_SWITCHCAPVCC, 0x3D);  // initialize with the I2C addr 0x3D (for the 128x64)

becomes:

void setup()   {                
  Serial.begin(9600);
  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);  // initialize with the I2C addr 0x3C (for the 128x64)

Note: If this doesn’t work for some reason try using the i2c scanner from this instructable.

Done!