Content
# Tool List
ESP32 itself hosts an HTTP server, allowing motor control from anywhere via WiFi using a phone, PC, or AI. AI (like Claude) uses the standard MCP protocol, while humans control it through a browser or curl, all connecting to a single ESP32 without needing a separate server.
```
Claude (MCP tools) ─→ esp32-motor-mcp (Rust stdio MCP) ─→ HTTP ─→ ESP32 web server ─→ continuous rotation servo
phone browser / curl ──────────────────────────────────────→ ↗
```
- Firmware: Arduino code (supports both ESP32-S3 and regular ESP32). No additional libraries are required — it compiles directly with the ESP32 board package installed.
- MCP server: Written in Rust, using only a JSON processing library (serde_json) for lightweight implementation.
## 1. Preparation
| Component | Order Search Terms (Kupang/DeviceMart/Eleparts) | Notes |
|---|---|---|
| ESP32 development board (black, 2x USB-C) | **ESP32-S3-DevKitC-1** or "ESP32-S3 development board N16R8" | Regular "ESP32 DevKit V1" (WROOM-32) with only 1x USB-C also works |
| Blue small motor (360-degree rotation) | **FS90R continuous rotation servo** or "SG90 360-degree continuous rotation servo" | Regular SG90 (180-degree) cannot rotate wheels — ensure "360-degree/continuous rotation" is specified |
| Connection wires | 3x F-M jumper cables | Servo cable 3-pin |
Regular SG90 = angle control (0~180 degrees). For commands like "turn 2 circles," a continuous rotation type is required.
## 2. Wiring
| Servo wire | ESP32 pin |
|---|---|
| Orange/Yellow (signal) | GPIO 4 |
| Red (VCC) | 5V (VIN) |
| Brown/Black (GND) | GND |
One 5V USB power supply is sufficient for one servo. For multiple servos, use a separate 5V power supply.
## 3. Firmware Upload (Arduino IDE)
1. Install Arduino IDE → Preferences → Additional Board Manager URL: `https://espressif.github.io/arduino-esp32/package_esp32_index.json`
2. Install "esp32 by Espressif" in Board Manager
3. Select board: **ESP32S3 Dev Module** (or "ESP32 Dev Module" for regular ESP32)
4. Upload → Connect to serial monitor (115200 baud) to see SSID and IP output. Then, disconnect USB (only power is needed)
WiFi connection sequence (automatic):
1. **Registered router** — router name and password are stored in the board's internal storage (NVS) once and can be reused.
2. If no registered router or connection fails, it searches for nearby open WiFi networks and attempts to connect to up to 5 networks in order of signal strength.
3. If that also fails, the board creates a temporary WiFi network (`ESP32-MOTOR` / password `motor1234`) → connect via phone browser to `http://192.168.4.1`
## 4. Usage
### Phone/PC Browser
`http://<ESP32_IP>/` — button UI (left/right N circles, continuous rotation, stop, sequence)
### API (curl / Claude / Automation)
```bash
# Example: "Turn left 2 circles, wait 1 second, turn right 1 circle"
curl "http://<IP>/api/seq?seq=L2,W1,R1"
curl "http://<IP>/api/turn?dir=left&turns=2" # Turn left 2 circles
curl "http://<IP>/api/turn?dir=right&turns=1&speed=50" # 50% speed
curl "http://<IP>/api/seq?seq=S-100" # Left infinite rotation
curl "http://<IP>/api/stop" # Stop
curl "http://<IP>/api/status" # Status JSON
```
Sequence syntax (universal — can express any command):
| Token | Meaning |
|---|---|
| `L<circles>` / `R<circles>` | Left/right n circles. Decimal values allowed (`L0.25` = 90 degrees left) |
| `W<seconds>` | Wait |
| `S<±speed%>` | Continuous rotation (negative = left), until `/api/stop` |
| `S<±speed%>X<seconds>` | Timed rotation (`S-50X3` = left 50% for 3 seconds) |
| `@<speed%>` | Step speed (`L2@50` = left 2 circles at half speed) |
| `&repeat=N` | Repeat sequence N times |
## 5. MCP Remote Control (AI Natural Language Control)
The `mcp-server/` folder contains the MCP server, allowing AI to use ESP32 functions as standard tools. Claude Code registered with user scope (`claude mcp list` → esp32-motor Connected).
| MCP tool | Function |
|---|---|
| `motor_status` | Status query (rotating/queue/calibration value/IP/signal strength) |
| `motor_turn` | Direction + circles + speed rotation |
| `motor_seq` | Universal sequence execution (L/R/W/S syntax + repeat) |
| `motor_stop` | Immediate stop |
| `motor_calibrate` | Calibration value setting (permanently stored on board) |
| `motor_cal_run` | 10-second rotation calibration helper |
Usage: In Claude session, say "Motor turn left 2 circles, wait 1 second, turn right 1 circle" → automatically calls `motor_seq(seq="L2,W1,R1")`.
## 6. Frequently Asked Questions
### Before Starting
**Q. Can I do this without knowing electronics?**
A. Yes. No soldering required. Just connect 3 wires to pins and upload the program via USB.
**Q. How much do the parts cost?**
A. Approximately 2~3 million KRW (subject to change). Any Windows/Mac computer works.
**Q. I already have a regular SG90 servo. Can I use it?**
A. No. SG90 only controls angles (0~180 degrees). For commands like "turn 2 circles," a continuous rotation type (FS90R series) is required.
### Board Connection and Driver
**Q. My computer doesn't recognize the board when I plug it in.**
1. Common issue: Use a different cable — "charging only" cables don't transmit data.
2. Driver issue: Install the correct driver from the manufacturer's website.
**Q. Which USB port should I use on the ESP32-S3 board?**
A. The port labeled "COM"/"UART".
### Firmware Upload
**Q. The port (COM) doesn't appear in the list.**
A. Ensure the board is recognized. Solve driver issues first.
**Q. I get a "Failed to connect" error during upload.**
A. Press the **BOOT button** while uploading.
**Q. Which board should I select?**
A. For ESP32-S3: "ESP32S3 Dev Module". For regular ESP32: "ESP32 Dev Module".
**Q. The serial monitor shows gibberish characters.**
A. Set the baud rate to **115200**.
### Wiring
**Q. How do I connect the 3 servo wires?**
| Servo wire color | Board pin | Meaning |
|---|---|---|
| Orange (or Yellow) | GPIO 4 | Signal |
| Red | 5V (or VIN) | Power |
| Brown (or Black) | GND | Ground |
### WiFi Connection
**Q. I'm having trouble connecting to my home WiFi.**
A. ESP32 only supports **2.4GHz**.
**Q. How do I enter my WiFi password?**
A. Don't write it in the code. Use serial monitor or web interface.
**Q. What if I enter the wrong password?**
A. Re-enter using the same method.
### Motor Operation
**Q. The motor doesn't move at all.**
1. Check wiring.
2. Test using the browser interface.
**Q. The motor trembles or lacks power.**
A. Insufficient USB power. Try a wall charger.
### AI / MCP Control
**Q. What is MCP? Is it necessary?**
A. MCP is a protocol for AI to use external tools. Not necessary, but provides a standardized way for voice control.
**Q. How do I control the motor with AI?**
A. Register MCP and give voice commands like "Motor turn left 2 circles, wait 1 second, turn right 1 circle".
