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.