Add quick start guide for rapid deployment
This commit is contained in:
252
docs/QUICK_START.md
Normal file
252
docs/QUICK_START.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user