# Quick Start Guide

Get your ESP32 8-channel relay controller up and running in 15 minutes!

## What You Need

- ESP32 development board
- 8-channel relay module (5V)
- 8+ jumper wires (male-to-female)
- USB cable for ESP32
- Computer with Arduino IDE

## Step 1: Wire It Up (5 minutes)

### Power Connections
```
ESP32 5V  ──→ Relay Module VCC
ESP32 GND ──→ Relay Module GND
```

### GPIO Connections (Default Configuration)
```
ESP32 GPIO → Relay Module
------------------------
GPIO 13    → IN1
GPIO 12    → IN2
GPIO 14    → IN3
GPIO 27    → IN4
GPIO 26    → IN5
GPIO 25    → IN6
GPIO 33    → IN7
GPIO 32    → IN8
```

**Quick Tip:** Use different colored wires to avoid confusion!

## Step 2: Install Software (5 minutes)

### Option A: Arduino IDE (Recommended for Beginners)

1. **Install ESP32 Board Support**
   ```
   File → Preferences → Additional Board Manager URLs
   Add: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   
   Tools → Board → Board Manager → Search "ESP32" → Install
   ```

2. **Configure Board**
   ```
   Tools → Board → "ESP32 Dev Module"
   Tools → Upload Speed → "115200"
   ```

3. **Open the Sketch**
   - Open `esp32_bluetooth_relay.ino`

### Option B: PlatformIO (For Advanced Users)

```bash
# Navigate to project folder
cd esp32-bluetooth-relay

# Build and upload
pio run --target upload

# Monitor serial output
pio device monitor
```

## Step 3: Upload Code (2 minutes)

1. Connect ESP32 to computer via USB
2. Select correct COM port: `Tools → Port`
3. Click **Upload** button (→)
4. Wait for "Done uploading" message

**Troubleshooting Upload:**
- Hold BOOT button on ESP32 while uploading starts
- Try different USB cable/port
- Check driver installation

## Step 4: Test Connection (3 minutes)

### On Mobile (Easiest)

1. **Download a Bluetooth Terminal App**
   - Android: "Serial Bluetooth Terminal"
   - iOS: "Bluetooth Terminal"

2. **Pair and Connect**
   - Open Bluetooth settings
   - Look for "ESP32-Relay-8CH"
   - Pair (PIN: 1234 if asked)

3. **Open Terminal App**
   - Connect to ESP32-Relay-8CH
   - Type: `STATUS` (press Enter)
   - You should see relay status!

### On Computer

**Windows:**
1. Pair with ESP32 via Bluetooth settings
2. Note the COM port number
3. Open PuTTY or Arduino Serial Monitor
4. Connect to the COM port at 115200 baud

**Linux:**
```bash
# Find ESP32 MAC address
hcitool scan

# Pair
bluetoothctl
> pair XX:XX:XX:XX:XX:XX
> trust XX:XX:XX:XX:XX:XX
> connect XX:XX:XX:XX:XX:XX

# Connect with screen or minicom
sudo rfcomm bind /dev/rfcomm0 XX:XX:XX:XX:XX:XX
screen /dev/rfcomm0 115200
```

## First Commands to Try

```
STATUS      # See all relay states
ON1         # Turn on relay 1
OFF1        # Turn off relay 1
TOGGLE1     # Toggle relay 1
ALL_ON      # Turn all relays on
ALL_OFF     # Turn all relays off
HELP        # Show all commands
```

## Quick Troubleshooting

### "Can't find ESP32-Relay-8CH"
- Power cycle the ESP32
- Check if Bluetooth is enabled on your device
- Unpair and re-pair if previously connected
- Check Serial Monitor for "Bluetooth device ready" message

### "Relays not switching"
- Verify wiring matches the pin assignments
- Check relay module power (VCC and GND)
- Try different GPIO pins
- Test with multimeter

### "Upload failed"
- Hold BOOT button during upload
- Check USB cable (data cable, not charge-only)
- Install CP210x or CH340 drivers
- Try different USB port

### "Wrong direction" (relay ON when should be OFF)
- Your relay module is Active HIGH
- Change code in `setRelay()` function:
  ```cpp
  digitalWrite(relayPins[relayIndex], state ? HIGH : LOW);
  ```

## Safety First! ⚠️

**Before connecting any loads:**
1. ✅ Test with low voltage (12V DC LED strip, for example)
2. ✅ Verify relay is switching correctly
3. ✅ Double-check wiring
4. ✅ Use proper fuses
5. ⚠️ NEVER work on AC wiring while powered

**For AC loads:**
- Consider hiring an electrician
- Use proper electrical enclosures
- Follow local electrical codes
- Add fuses or circuit breakers

## What's Next?

### Customize Your Setup
- Edit relay names in code
- Change GPIO pins if needed
- Modify Bluetooth device name
- Add custom commands

### Integration Ideas
- Control via Home Assistant
- Add scheduling/timers
- Create scenes (groups of relays)
- Add web interface
- MQTT integration

### Upgrade Options
- Add WiFi control
- Use ESPHome firmware
- Add temperature sensors
- Energy monitoring
- Remote access via VPN

## Need Help?

**Check these resources:**
1. Full README.md - Comprehensive documentation
2. Shopping list - Hardware recommendations
3. Troubleshooting section in README
4. Open an issue on repository
5. ESP32 community forums

## Cheat Sheet

**Common Commands:**
```
ON1-8      Turn on relay 1-8
OFF1-8     Turn off relay 1-8
TOGGLE1-8  Toggle relay 1-8
ALL_ON     All on
ALL_OFF    All off
STATUS     Show states
HELP       Show commands
```

**Serial Monitor Commands:**
```
Upload Code: Ctrl+U (Arduino IDE)
Open Monitor: Ctrl+Shift+M
Clear Monitor: Click trash icon
```

**Useful GPIO Pins (ESP32):**
```
Safe for output: 13,12,14,27,26,25,33,32
Avoid: 6-11 (flash), 0,2 (boot), 34-39 (input only)
```

## Success Checklist

- [ ] ESP32 powered on
- [ ] Relay module powered
- [ ] All GPIOs connected
- [ ] Code uploaded successfully
- [ ] Can pair via Bluetooth
- [ ] STATUS command works
- [ ] Relay clicks when toggled
- [ ] Tested with safe load (LED/bulb)

**Congratulations! Your ESP32 relay controller is ready to use!** 🎉

---

**Version:** 1.0  
**Last Updated:** December 2025