diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md new file mode 100644 index 0000000..572acf0 --- /dev/null +++ b/docs/QUICK_START.md @@ -0,0 +1,252 @@ +# 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