Using an OLED Display with your ESP32 on VS Code

Posted: November 13, 2023
Last Updated: November 29, 2023

Want to display text or graphics with your OLED display using an ESP32? Interested in knowing how to do it in VS Code? Read the article to find out.

Introduction

OLEDs are a great way to display data from your microcontroller to the outside world. Some of our previous blogs have already done and explained the process of doing it. However, how do you do it on an ESP32 device? Here, you’ll learn the specifics.

Connecting your OLed with your esp32 device

Wether it’s an ESP32, ESP32-S2, ESP32-S3, or other models, the process of connecting your OLED screen should be similar. What’s important is to find your ESP32’s I2C port. After that, directly connect this port to your OLED display’s I2C port. Here, we have pin 9 to be SCL and pin 8 to be SDA on ESP32-S2 or S3 DevKitC.

Additionally, connect the VCC and GND terminals of the OLED display to your ESP32’s system power. A typical 128×64 OLED can be powered with a +3.3V or 5V supply. With this, connect your OLED’s power terminals to the +3.3V and GND terminals of your ESP32 component or devkit.

Using VSCODE to program the display of your OLED

Previously, the way to use components on ESP-IDF was discussed. This was followed by an example of adding a component utilizing an OLED screen from the ESP-IDF Component Registry. However, this time around, a third-party component will be used. A popular maker from Japan nicknamed nopnop2002 creates ESP-IDF components. We’ll use his esp-idf-ssd1306 component, which uses a menu configuration to configure OLED parameters. This provides a better visual interaction with the user as he or she adjusts the parameters.

Demo Run OF nopnop2002's SSD1306 component

Download nopnop2020/esp-idf-ssd1306 and then open the TextDemo folder in Visual Studio Code through File -> Open Folder… Having read our previous blog about running programs in ESP-IDF in VS Code, run menu configuration and ensure you have pin 8 as SDA and pin 9 as SCL (or use what you have). You can put -1 on RESET if your OLED does not have a reset pin. Choose a Panel type of 128×64 OLED screen if you have that kind of panel, otherwise, choose your own.

Build and Run it on your ESP32 board to see how the OLED Text demo runs.

How to Incorporate nopnop's SSD1306 Component into your Projects

Adding nopnop’s SSD1306 component to your projects is easy. Copy the component folder from nopnop’s SSD1306 directory to your project’s directory. It’s as simple as that. You can test it out by creating a new project and then adding the component folder to your new project’s folder.

On your new project’s main.c file, don’t forget to include the ssd1306.h header file.

				
					#include "ssd1306.h"

Go ahead and paste the code below to your main file. Configure, Build, and Run the code and see the output.

				
					#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"

#include "ssd1306.h"
#include "font8x8_basic.h"

/*
 You have to set this config value with menuconfig
 CONFIG_INTERFACE

 for i2c
 CONFIG_MODEL
 CONFIG_SDA_GPIO
 CONFIG_SCL_GPIO
 CONFIG_RESET_GPIO

 for SPI
 CONFIG_CS_GPIO
 CONFIG_DC_GPIO
 CONFIG_RESET_GPIO
*/

#define tag "SSD1306"

void app_main(void)
{
	SSD1306_t dev;
	int center, top, bottom;
	char lineChar[20];

#if CONFIG_I2C_INTERFACE
	ESP_LOGI(tag, "INTERFACE is i2c");
	ESP_LOGI(tag, "CONFIG_SDA_GPIO=%d",CONFIG_SDA_GPIO);
	ESP_LOGI(tag, "CONFIG_SCL_GPIO=%d",CONFIG_SCL_GPIO);
	ESP_LOGI(tag, "CONFIG_RESET_GPIO=%d",CONFIG_RESET_GPIO);
	i2c_master_init(&dev, CONFIG_SDA_GPIO, CONFIG_SCL_GPIO, CONFIG_RESET_GPIO);
#endif // CONFIG_I2C_INTERFACE

#if CONFIG_SPI_INTERFACE
	ESP_LOGI(tag, "INTERFACE is SPI");
	ESP_LOGI(tag, "CONFIG_MOSI_GPIO=%d",CONFIG_MOSI_GPIO);
	ESP_LOGI(tag, "CONFIG_SCLK_GPIO=%d",CONFIG_SCLK_GPIO);
	ESP_LOGI(tag, "CONFIG_CS_GPIO=%d",CONFIG_CS_GPIO);
	ESP_LOGI(tag, "CONFIG_DC_GPIO=%d",CONFIG_DC_GPIO);
	ESP_LOGI(tag, "CONFIG_RESET_GPIO=%d",CONFIG_RESET_GPIO);
	spi_master_init(&dev, CONFIG_MOSI_GPIO, CONFIG_SCLK_GPIO, CONFIG_CS_GPIO, CONFIG_DC_GPIO, CONFIG_RESET_GPIO);
#endif // CONFIG_SPI_INTERFACE

#if CONFIG_FLIP
	dev._flip = true;
	ESP_LOGW(tag, "Flip upside down");
#endif

#if CONFIG_SSD1306_128x64
	ESP_LOGI(tag, "Panel is 128x64");
	ssd1306_init(&dev, 128, 64);
#endif // CONFIG_SSD1306_128x64
#if CONFIG_SSD1306_128x32
	ESP_LOGI(tag, "Panel is 128x32");
	ssd1306_init(&dev, 128, 32);
#endif // CONFIG_SSD1306_128x32


#if CONFIG_SSD1306_128x64
	top = 2;
	center = 3;
	bottom = 8;
#endif // CONFIG_SSD1306_128x64

#if CONFIG_SSD1306_128x32
	top = 1;
	center = 1;
	bottom = 4;
#endif // CONFIG_SSD1306_128x32

// main code
	while(1)
	{
		vTaskDelay(3000 / portTICK_PERIOD_MS);

		// Hello World
		ssd1306_display_text(&dev, 0, "Hello World", 12, false);

		vTaskDelay(3000 / portTICK_PERIOD_MS);

		ssd1306_clear_screen(&dev, false);
	}

}