Using ESP32 with Waveshare OLEDs and Adafruit Graphics

Sharing how to do since it took me a bit to get working (and this way I can set it up again in the future when I forget).

Components:

I happen to have two of the OLED displays, so I'll share setting both of them up. There are only minor differences.

The main thing to know is that the 1.5" uses an SSD1327 controller and the 1.27" uses an SSD1351 controller.

Wiring Up

The displays come with a wired connector which makes things easier, but the 1.5" also has solder connections if you want to use them. I used a 90° header so the screen could stand up on a bread board.

Here's how I connected the displays to the ESP32:

3V -> VCC
GND -> GND
SCK -> CLK
MO -> DIN
13 -> DC
27 -> CS
33 -> RST

The numbered pins can be changed if you want, but make sure you avoid using 12 (the docs say this is "a special 'boot strapping' pin on the ESP32, this pin must be low when the board is powered on/reset but can then be used as an output or input." - I find it easier to avoid).

Arduino Setup

Libraries

Install "Adafruit GFX library"

For the 1.5" display:

Install "Adafruit SSD1327 library" - https://github.com/adafruit/Adafruit_SSD1327

For the 1.27" display:

Install "Adafruit SSD1351 library" - https://github.com/adafruit/Adafruit-SSD1351-library

Both of these are available inside the Arduino IDE library. Just search and install.

Board

Instructions here.

Be sure to select "Adafruit ESP32 Feather v2" as the board type (if that's what you are using!)

Test Programs

Copy the test program.

For the 1.5" display: https://github.com/adafruit/Adafruit_SSD1327/blob/master/examples/ssd1327_test/ssd1327_test.ino

For the 1.27" display: https://github.com/adafruit/Adafruit-SSD1351-library/blob/master/examples/test/test.ino

Pin Configuration

For the 1.5" (square) display, change the start of the example code to:

// Used for software SPI
#define OLED_CLK SCK
#define OLED_MOSI MOSI

// Used for software or hardware SPI
#define OLED_CS 27
#define OLED_DC 13

// Used for I2C or SPI
#define OLED_RESET 33

// hardware SPI
Adafruit_SSD1327 display(128, 128, &SPI, OLED_DC, OLED_RESET, OLED_CS);

For the 1.27", change the start of the example code to:

// Screen dimensions
#define SCREEN_WIDTH  128
#define SCREEN_HEIGHT 96

#define SCLK_PIN SCK
#define MOSI_PIN MOSI
#define DC_PIN   13
#define CS_PIN   27
#define RST_PIN  33

// Use the hardware SPI pins 
Adafruit_SSD1351 tft = Adafruit_SSD1351(SCREEN_WIDTH, SCREEN_HEIGHT, &SPI, CS_PIN, DC_PIN, RST_PIN);