# esp32-with-ssd1306-example

> 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°.

- Author: Mikrobot.pl
- Platform: ESP32
- Board: ESP32 Dev Module (`esp32:esp32:esp32`)
- SDK version: 3.3.6
- Tags: #esp32, #oled, #ssd1306, #captive portal, #arduino, #i2c
- Created: 2026-06-01
- Updated: 2026-06-01
- Favorites: 1, forks: 1
- Forked from: [Mikrobot.pl/esp8266-with-ssd1306-example](https://flashesp.com/explore/w1IdfV9wVa0RONQSQDUjp.md)
- Project page (view, flash from the browser, fork): https://flashesp.com/explore/T0UdlnvvD2YFXBHHzCadT
- Download all sources (zip): https://flashesp.com/api/public-projects/T0UdlnvvD2YFXBHHzCadT/download-sources/

## Source files

- [libraries_lock.json (244 B)](https://flashesp.com/explore/T0UdlnvvD2YFXBHHzCadT/files/tGMc6mtKe0CGDVQwsdEn2.md)
- [main.ino (5.2 KB)](https://flashesp.com/explore/T0UdlnvvD2YFXBHHzCadT/files/rA4dEHdSLAuwPlVZcZL1x.md)
- readme.md (4.3 KB)

## 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:

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

The OLED address is usually:

~~~cpp
#define OLED_ADDR 0x3C
~~~

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

~~~cpp
#define OLED_ADDR 0x3D
~~~

---

## Onboard LED

The sketch uses:

~~~cpp
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:

~~~text
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:

~~~text
mikrobot-portal
~~~

4. Connect to this Wi-Fi network from your phone or laptop.
5. Open any website. It should redirect to the captive portal.
6. You can also open the portal directly:

~~~text
http://192.168.4.1
~~~

7. Enter new text and press **Update OLED**.

The OLED updates immediately.

---

## Customization

### Change Wi-Fi Name

Change the access point name in the sketch:

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

Example:

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

---

### Add a Wi-Fi Password

By default, the Wi-Fi network is open:

~~~cpp
static const char* AP_PASS = "";
~~~

To add a password, set at least 8 characters:

~~~cpp
static const char* AP_PASS = "12345678";
~~~

---

### Rotate the Display

If the OLED is upside down, change:

~~~cpp
display.setRotation(0);
~~~

to:

~~~cpp
display.setRotation(2);
~~~

Available rotation values:

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

---

### Change the Default Text

Change this line:

~~~cpp
String currentText = "mikrobot.pl";
~~~

Example:

~~~cpp
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:

~~~text
mikrobot-portal
~~~

---

### Captive portal does not open automatically

Open the portal manually in a browser:

~~~text
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:

~~~text
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**
