readme.md

Markdown · 175 lines

# ESP32-C3 Super Mini — LED Captive Portal
### Control the on-board LED via WiFi with an automatic captive portal

This project turns an **ESP32-C3 Super Mini** into a WiFi-controlled LED module.  
When powered, the board creates an **open WiFi Access Point** and a **captive portal**.  
As soon as a device connects to the AP, a control page appears automatically — letting you **turn the LED ON or OFF** from any browser, with no app and no internet required.

---

## ⭐ Features

- **Open WiFi Access Point** — no password needed  
  - SSID: `ESP32-C3-LED`
- **Automatic captive portal**  
  - Any URL (e.g. `google.com`) is redirected to the LED control page  
  - Compatible with Android / iOS / macOS / Windows / Linux
- **Web-based LED control**  
  - One-tap buttons: **Turn ON** / **Turn OFF**  
  - Live status displayed on the page
- **No external network or internet required** — fully self-contained

---

## 📦 Hardware Requirements

| Item | Notes |
|------|-------|
| **ESP32-C3 Super Mini** | WiFi + BT 5.0, USB-C, ~22×18 mm |
| USB-C cable | For power and flashing |
| *(optional)* External LED + 220 Ω resistor | If you prefer an external indicator |

### On-board LED

The **ESP32-C3 Super Mini** has a built-in **blue LED** on **GPIO 8**.  
This LED is **active LOW** (writing `LOW` turns it ON, `HIGH` turns it OFF).  
The firmware handles this automatically via the `ACTIVE_LOW` flag.

```cpp
#define LED_PIN    8      // on-board blue LED
#define ACTIVE_LOW true   // LOW = ON, HIGH = OFF
```

#### Using an external LED instead

1. Connect the LED anode → GPIO pin of your choice → 220 Ω resistor → 3.3 V or → GND.
2. Change `LED_PIN` to your GPIO number.
3. Set `ACTIVE_LOW false` if the LED turns on with `HIGH`.

> ⚠️ **Avoid GPIO 2, 8, and 9** during boot — they are strapping pins on the ESP32-C3.  
> GPIO 8 is safe to use *after* boot (it is used by the on-board LED by design).

---

## 🛠️ Arduino IDE Setup

### 1 — Install the ESP32 Board Package

Open **File → Preferences** and add the following URL to *Additional boards manager URLs*:

```
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
```

Then open **Tools → Board → Boards Manager**, search for **esp32** by Espressif, and install version **≥ 2.0.14**.

### 2 — Board Settings

Go to **Tools** and set each option as shown:

| Setting | Value |
|---------|-------|
| Board | `ESP32C3 Dev Module` |
| **USB CDC On Boot** | **Enabled** ← critical for Serial over USB-C |
| CPU Frequency | 160 MHz |
| Flash Mode | QIO 80MHz |
| Flash Size | 4MB (32Mb) |
| Partition Scheme | Default 4MB with spiffs |
| Upload Speed | 921600 |
| Erase All Flash Before Sketch Upload | Disabled |

> ⚠️ **"USB CDC On Boot: Enabled"** is required for `Serial.print()` to appear in the Serial Monitor when using the USB-C port directly.  
> Without it, all Serial output will be silently dropped.

### 3 — Select the Port

Connect the board via USB-C.  
On Windows the port appears as **COMx**; on Linux/macOS as **/dev/ttyACM0** or **/dev/ttyUSB0**.

### 4 — Upload

Open `esp32c3_led_captive_portal.ino`, click **Upload** (→).  
If the upload fails, hold the **BOOT** button on the board while clicking Upload, then release it once the upload starts.

---

## 🚀 Usage

1. **Power the board** via USB-C.
2. **Connect your phone or laptop** to the WiFi network **`ESP32-C3-LED`** (open, no password).
3. A browser page opens automatically — if it doesn't, navigate to **`http://192.168.4.1`**.
4. Press **Turn ON** or **Turn OFF** to control the LED.

### Serial Monitor output (115200 baud)

```
=== ESP32-C3 Super Mini — LED Captive Portal ===
LED pin: GPIO 8  |  active-LOW
WiFi AP started  SSID: ESP32-C3-LED
AP IP address  : 192.168.4.1
HTTP server started on port 80.
DNS captive portal active — all domains -> 192.168.4.1
================================================
```

---

## 📡 Captive Portal Compatibility

The firmware handles detection endpoints for all major platforms:

| Platform | Endpoint |
|----------|----------|
| Android | `/generate_204` |
| iOS / macOS | `/hotspot-detect.html` |
| Windows | `/ncsi.txt` |
| Linux / Firefox | `/connectivity-check` |
| Everything else | `404 → redirect to /` |

---

## 📁 File Structure

```
esp32c3_led_captive_portal/
├── esp32c3_led_captive_portal.ino   # Main sketch
└── README.md                        # This file
```

---

## 🔌 Pin Reference — ESP32-C3 Super Mini

```
         USB-C
    ┌─────┤├─────┐
  5V│  1        │GND
 GND│  2        │3V3
  TX│  3        │GND
  RX│  4      ←─┤GPIO 10
 GND│  5      ←─┤GPIO 9
    │  GND    ←─┤GPIO 8  ← on-board LED (active LOW)
    │  3V3    ←─┤GPIO 7
    │  GND    ←─┤GPIO 6
    │  GPIO 0 ←─┤GPIO 5
    │  GPIO 1 ←─┤GPIO 4
    │  GPIO 2 ←─┤GPIO 3
    └──────────────┘
```

> Pinout may vary slightly by manufacturer — always verify against your board's silkscreen.

---

## ⚙️ Configuration Reference

All user-adjustable constants are at the top of the `.ino` file:

```cpp
#define LED_PIN     8           // GPIO for the LED
#define ACTIVE_LOW  true        // true = on-board LED; false = most external LEDs
const char* AP_SSID = "ESP32-C3-LED";   // WiFi network name
IPAddress apIP(192, 168, 4, 1);         // AP IP address
```