readme.md

Markdown · 146 lines

# ESP32 Single-Channel Relay Controller (Relay 5V 10A High Level)

This project turns an ESP32 (e.g. ESP32 DevKit / ESP32-WROOM dev board) into an **open Wi-Fi Access Point** with a **captive portal** (no login page) that lets you **switch a relay ON/OFF** from a browser, on your phone or computer.

The relay module used here is configured for **High Level trigger** mode (some Mikrobot 1-channel modules have an LL/HL jumper or switch — make sure it's set to HL).

---

## Features

- Open Wi-Fi AP (no password) for quick access
- Captive portal using DNS wildcard (redirects any domain to the ESP32)
- Web dashboard (`/`) with an ON/OFF button and live relay state
- JSON endpoint (`/data`) for live state polling
- Safe boot state — the relay is forced OFF before anything else runs
- Correct handling of **High Level** trigger logic — see note below

---

## Hardware

- ESP32 development board (e.g. ESP32 DevKit V1 / ESP32-WROOM-32)
- **Mikrobot 1-Channel 5V 10A** relay module, set to **High Level** trigger mode
- Jumper wires / breadboard
- A load to switch (a lamp, pump, low-voltage contact, etc.)

> **If you plan to switch 230V AC mains:** read the "Safety" section below before wiring anything.

---

## Important note: this module's "High Level" logic

This relay module **energizes the coil when the IN pin is pulled HIGH**, not LOW.

**IN PRACTICE:**
- `IN = HIGH` → relay **ON** (COM-NO contact closed)
- `IN = LOW` → relay **OFF** (COM-NO contact open)

For this reason, the control pin is set to **LOW at the very start of `setup()`**, before anything else runs (Wi-Fi, web server). An ESP32 GPIO already defaults to LOW on reset/boot, so in High Level mode the relay is inherently off at power-on — the explicit `digitalWrite` in `setup()` just makes that state unambiguous rather than relying on it.

> **Note on 3.3V logic:** if you previously tried this same module in Low Level mode and it didn't switch reliably from a 3.3V ESP32 GPIO, that was because its input stage couldn't tell a 3.3V "high" apart from a true 5V "high". In **High Level** mode you don't run into that ambiguity in the same way — any clearly-non-zero voltage on IN reads as "high" — but if you still see unreliable switching, test the module directly with a wire to GND (OFF) and to 5V (ON) to confirm the module itself responds correctly before suspecting the ESP32 side again.

---

## Wiring (recommended mapping)

The module has 3 control pins plus 3 relay output terminals.

Control side (to ESP32):
- VCC → **5V** (the "5V"/"VIN" pin on the ESP32 dev board, i.e. the USB power rail)
- GND → **GND**
- IN → **GPIO26**

Output side (relay screw terminals):
- **COM** — common
- **NO** — normally open (connects to COM when the relay is energized)
- **NC** — normally closed (connects to COM when the relay is de-energized)

For most use cases (turn a load on/off) you'll use **COM + NO**.

### Why 5V and not 3.3V?

The relay coil is rated for 5V. The module's IN pin also accepts 3.3V logic from an ESP32 GPIO (the switching threshold is low enough), but **the coil supply (VCC) must come from 5V**, otherwise the relay won't switch reliably or at all.

### Note about ESP32 strapping pins

ESP32 has several **strapping pins** that affect boot mode and must be free of external pull-down/pull-up at reset: **GPIO0, GPIO2, GPIO12, GPIO15**. Avoid using any of these as the relay IN pin. Safe general-purpose choices include GPIO26, GPIO27, GPIO25, GPIO32, GPIO33 (exact availability depends on your specific board/module).

---

## Safety (read this if you're switching mains voltage)

This module is rated for **up to 10A/250V AC or 15A/125V AC** on the relay contact side — enough to switch 230V mains.

- Always disconnect the mains circuit from power before touching the COM/NO/NC terminals.
- Once mains wiring is connected, enclose the module — never leave live terminals exposed.
- The low-voltage side (ESP32, IN, GND, 5V VCC) and the high-voltage side (COM/NO/NC) are physically separated on the board — never bridge their grounds or wiring.
- If you're unsure about wiring 230V AC, consult someone qualified to work with mains electricity.
- This project does not replace proper circuit protection (fuse, RCD/GFCI).

---

## Software Requirements

- Arduino IDE (or PlatformIO)
- ESP32 board support installed in Arduino IDE

### Installing ESP32 board support (Arduino IDE)

1. File → Preferences → "Additional Boards Manager URLs" → add:
   `https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`
2. Tools → Board → Boards Manager → search "esp32" → install the **esp32 by Espressif Systems** package
3. Tools → Board → select your board, e.g. **"ESP32 Dev Module"**

### Libraries

No extra libraries need to be installed from the Library Manager. The sketch only uses libraries built into the ESP32 Arduino core:
- WiFi
- WebServer
- DNSServer

These are installed automatically together with the ESP32 board package above.

---

## How to Use

1. Flash the firmware to the ESP32.
2. Power the board.
3. Connect your phone/PC to the Wi-Fi network:
   - SSID: `Relay-Portal`
4. The captive portal should open automatically.
   - If it does not, open: `http://192.168.4.1/`
5. Press the **ON/OFF** button on the page to toggle the relay. The current state refreshes automatically.

---

## Endpoints

- GET `/`       : web UI
- GET `/data`   : JSON with relay state
- GET `/on`     : forces the relay ON
- GET `/off`    : forces the relay OFF
- GET `/toggle` : flips the current state

Example JSON:
```
{
  "relay": "ON",
  "trigger_level": "HIGH",
  "uptime_ms": 125340
}
```

---

## Troubleshooting

- The relay clicks once at ESP32 boot:
  - usually caused by a briefly floating GPIO right after reset — make sure `digitalWrite(RELAY_PIN, RELAY_OFF)` is the very first instruction in `setup()`
- The relay behaves "inverted" (turns ON when you expect OFF):
  - confirm your unit is actually set to **High Level** mode — some Mikrobot modules have an LL/HL jumper that changes the logic; if it's stuck in Low Level, swap `RELAY_ON`/`RELAY_OFF` back or move the jumper
- ESP32 sometimes fails to boot after wiring the module:
  - don't use GPIO0, GPIO2, GPIO12, or GPIO15 as the IN pin (strapping pins) — move it to GPIO26/27/25/32/33
- The portal does not pop up automatically:
  - open `http://192.168.4.1/` manually