readme.md

Markdown · 133 lines

<p align="center">
  <img src="https://i.imgur.com/HmKC8SS.png" alt="ESP32 MG995 Servo Portal" width="320" style="display:inline-block; vertical-align:top; margin:0 8px;">
  <img src="https://i.imgur.com/KZkNXOM.jpeg" alt="MG995 servo" width="380" style="display:inline-block; vertical-align:top; margin:0 8px;">
</p>

# ESP32 MG995 Servo Portal  
### Wireless servo control with captive portal on ESP32 Dev Module

This project turns an **ESP32 Dev Module** plus a **TowerPro MG995 servo** into a wireless servo tester.

After power-up, the ESP32:

- creates an **open WiFi Access Point**,
- runs a **captive portal** (browser login page),
- shows a web page with a slider and preset buttons,
- moves the servo to the selected angle.

Default position on boot: **90°**  
The page also shows the live pulse width in microseconds and the current servo state.

---

## ⭐ Features

- **Open WiFi Access Point** (no password)
  - SSID: `ESP32-SERVO`
  - IP address: `192.168.4.1`
- **Captive portal**
  - Any domain (e.g. `google.com`) is redirected to the ESP32
  - Common OS captive checks handled by a single catch-all route:
    - Android `/generate_204`
    - iOS/macOS `/hotspot-detect.html`
    - Windows `/ncsi.txt`
- **Web interface**
  - Slider for 0–180° plus presets: 0 / 45 / 90 / 135 / 180
  - **Sweep** – continuous back-and-forth test run
  - **Release** – stops the pulse so the shaft goes limp and the servo stops heating
  - Status refreshes automatically every 400 ms
- **Precise control**
  - Pulse width sent directly in microseconds
  - 500–2500 µs mapped over 0–180° (11.11 µs per degree)

---

## 📦 Hardware requirements

- **ESP32 Dev Module** (DevKit v1, CP2102 or CH340 USB chip)
- **TowerPro MG995** servo (or any standard RC servo)
- Electrolytic capacitor **470–1000 µF / 10 V**
- Optional: external **5–6 V supply, 2 A or more**, for loaded operation

### ⚡ Powering the servo

> Power the servo from the **5V / VIN** pin, never from `3V3`. The `3V3` pin goes through the onboard AMS1117 regulator, which cannot drive a motor.

**Powering from the ESP32 (USB) works for bench testing.** With no load on the shaft the MG995 draws roughly 100–250 mA, which the USB rail handles — the `5V` pin is connected almost directly to USB 5 V, bypassing the 3.3 V regulator. The 470–1000 µF capacitor is what makes this reliable: it covers the short current spike each time the motor starts.

**Use a separate supply once the servo does real work.** Under load, when the shaft is held, or during fast direction reversals the current climbs to about 1 A and beyond. That exceeds the protection diode on most DevKit boards (often rated 1 A) and causes a voltage dip on the 5 V rail. The symptom is a resetting ESP32 with `Brownout detector was triggered` on the serial monitor, or dropped WiFi clients. A thin USB cable makes it worse, because the voltage drop happens before the board even sees the current.

### 🔌 MG995 → ESP32 wiring

The servo cable has three wires:

| Servo wire         | Connect to                               | Description                             |
|-------------------:|------------------------------------------|-----------------------------------------|
| Brown (or black)   | ESP32 `GND` (and PSU **–**)              | Ground – must be shared with the ESP32  |
| Red                | ESP32 `5V` / `VIN`, or PSU **+** (5–6 V) | Servo power – never `3V3`               |
| Orange (or yellow) | `GPIO13`                                 | PWM control signal                      |

The **shared ground is mandatory**. If you use an external supply, its minus must still be tied to the ESP32 `GND` — otherwise the servo has no reference for the control pulse and will jitter randomly.

Place the capacitor across the servo power rails (red ↔ brown), as close to the servo as possible.

```
5V / PSU + ──┬── red (servo)
             └── (+) 1000uF capacitor
GND / PSU - ─┬── brown (servo)
             ├── (-) 1000uF capacitor
             └── GND on ESP32          <-- shared ground
GPIO13     ───── orange (servo)
```

In the code the signal pin and the calibrated range are set as:

```cpp
#define SERVO_PIN 13
#define MIN_US    500   // 500 us  = 0 deg
#define MAX_US   2500   // 2500 us = 180 deg
#define MAX_DEG   180
```

Avoid the strapping pins (GPIO 0, 2, 12, 15) and GPIO 6–11 (flash). Safe alternatives: 14, 18, 19, 21, 22, 25, 26, 27, 32, 33.

---

## 📚 Library

The project uses the **ESP32Servo** library. It is already included here, so there is nothing to install.

`WiFi`, `WebServer` and `DNSServer` come with the ESP32 core. Note that the standard Arduino `Servo.h` does **not** work on the ESP32 — that is why `ESP32Servo` is used.

---

## 🧩 Board selection

Select the board **`ESP32 Dev Module`**.

Serial monitor speed: **115200 baud**.

---

## 🚀 How to use

1. Flash the project and power the ESP32 via USB.
2. On your phone or laptop, connect to the WiFi network **`ESP32-SERVO`**.
3. The captive portal page should open automatically.  
   If it does not, open **`http://192.168.4.1`** in your browser.
4. Drag the slider or press a preset button – the servo follows immediately.
5. Press **Sweep** for a continuous test run, **Release** to let the shaft go limp.

---

## 🛠 Troubleshooting

- **ESP32 reboots when the servo moves** – the 5 V rail is dipping. Add or increase the capacitor, use a thicker and shorter USB cable, and if the servo is under load, switch to a separate 5 V / 2 A supply with the grounds tied together.
- **Servo buzzes or heats up at 0° or 180°** – it is pressing against its end stop. Narrow the range to 600–2400 µs.
- **Servo jitters randomly** – missing common ground between the ESP32 and the servo supply.
- **The shaft turns further by hand than the slider reaches** – normal. The MG995 has a mechanical range of up to 270°, but the controller only accepts 500–2500 µs, which covers 180°. The rest cannot be reached in software.
- **Servo gets warm while holding position** – expected for a digital servo. Press **Release** to cut the pulse when you are not moving it.
- **Portal does not open automatically** – open `http://192.168.4.1` manually. Your phone may warn that the network has no internet access; choose to stay connected.
- **Redirect does not work for some websites** – only plain `http://` addresses are redirected. Sites opened via `https://` will show an error; use `http://192.168.4.1` instead.

> The WiFi network is open, so anyone nearby can connect and move the servo.