Back to Explorer

esp32-with-ssd1306-example

Project Information

Author

Mikrobot.pl

Board

ESP32 Dev Module

SDK Version

3.3.6

Platform

ESP32

Created

Updated

Description

ESP32 captive portal that lets you change the text shown on a 0.96" SSD1306 OLED (128×64). Starts with “mikrobot.pl”, rotates the display 180°.

Flash to Device

Login required: You need to login or create an account to flash this project.

Sorry, your browser doesn't support Web Serial.Web Serial requires HTTPS.

README

ESP32 OLED Captive Portal Text Display (mikrobot.pl)

This project turns an ESP32 dev board with an external 0.96" SSD1306 OLED display into a simple Wi-Fi captive portal.

After flashing, the OLED shows mikrobot.pl, and you can connect to the device’s Wi-Fi network to change the text displayed on the screen.


Features

  • Displays default text: mikrobot.pl
  • Supports SSD1306 OLED display over I2C
  • Wi-Fi captive portal
  • DNS redirects most domains to the local portal page
  • Web UI to update OLED text instantly
  • Uses an onboard LED heartbeat, usually on GPIO2

Hardware

  • ESP32 development board
  • External 0.96" SSD1306 OLED display
    • Resolution: 128×64
    • Interface: I2C
    • Typical I2C address: 0x3C
  • USB cable for programming and power

Wiring / Pins

Connect the external OLED display to the ESP32 as follows:

OLED Pin ESP32 Pin
VCC 3V3
GND GND
SDA GPIO21
SCL GPIO22

Important: Use 3.3V, not 5V, unless your OLED module specifically supports 5V logic.


OLED I2C Settings

The sketch uses the default ESP32 I2C pins:

static const uint8_t I2C_SDA = 21;
static const uint8_t I2C_SCL = 22;

The OLED address is usually:

#define OLED_ADDR 0x3C

If your display does not start, try changing the address to:

#define OLED_ADDR 0x3D

Onboard LED

The sketch uses:

static const uint8_t LED_PIN = 2;

On many ESP32 development boards, the onboard LED is connected to GPIO2.

If your board does not have an onboard LED, the project will still work. The LED heartbeat simply will not be visible.


Software Requirements

Arduino IDE

Install the ESP32 board package in Arduino IDE.

Then select a board such as:

ESP32 Dev Module

Libraries

Install these libraries using Arduino Library Manager:

  • Adafruit SSD1306
  • Adafruit GFX Library

These libraries come with the ESP32 board package:

  • WiFi
  • WebServer
  • DNSServer
  • Wire

How to Use

  1. Connect the OLED display to the ESP32.
  2. Flash the sketch to your ESP32.
  3. After boot, the ESP32 creates a Wi-Fi access point:
mikrobot-portal
  1. Connect to this Wi-Fi network from your phone or laptop.
  2. Open any website. It should redirect to the captive portal.
  3. You can also open the portal directly:
http://192.168.4.1
  1. Enter new text and press Update OLED.

The OLED updates immediately.


Customization

Change Wi-Fi Name

Change the access point name in the sketch:

static const char* AP_SSID = "mikrobot-portal";

Example:

static const char* AP_SSID = "my-oled-display";

Add a Wi-Fi Password

By default, the Wi-Fi network is open:

static const char* AP_PASS = "";

To add a password, set at least 8 characters:

static const char* AP_PASS = "12345678";

Rotate the Display

If the OLED is upside down, change:

display.setRotation(0);

to:

display.setRotation(2);

Available rotation values:

0 = normal
1 = 90 degrees
2 = 180 degrees
3 = 270 degrees

Change the Default Text

Change this line:

String currentText = "mikrobot.pl";

Example:

String currentText = "hello ESP32";

Troubleshooting

OLED stays blank

Check the following:

  • VCC is connected to 3V3
  • GND is connected to GND
  • SDA is connected to GPIO21
  • SCL is connected to GPIO22
  • OLED address is correct: 0x3C or 0x3D
  • The display is an I2C SSD1306 display, not SPI

Cannot see the Wi-Fi network

Check that the ESP32 is powered and the sketch uploaded successfully.

The Wi-Fi network should appear as:

mikrobot-portal

Captive portal does not open automatically

Open the portal manually in a browser:

http://192.168.4.1

Some phones or laptops may block automatic captive portal popups.


Notes

  • The ESP32 runs in Access Point mode.
  • The default IP address is:
192.168.4.1
  • The OLED is controlled over I2C.
  • No internet connection is provided by this Wi-Fi network.
  • The portal is only used to update the OLED text locally.

License

Use and modify freely for your own projects.

Project name: mikrobot.pl