esp32-with-ssd1306-example
Project Information
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.
Source Files (3)
Download AllREADME
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:
WiFiWebServerDNSServerWire
How to Use
- Connect the OLED display to the ESP32.
- Flash the sketch to your ESP32.
- After boot, the ESP32 creates a Wi-Fi access point:
mikrobot-portal
- Connect to this Wi-Fi network from your phone or laptop.
- Open any website. It should redirect to the captive portal.
- You can also open the portal directly:
http://192.168.4.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:
VCCis connected to3V3GNDis connected toGNDSDAis connected toGPIO21SCLis connected toGPIO22- OLED address is correct:
0x3Cor0x3D - 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