readme.md
Markdown · 270 lines
# 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**