Add comprehensive documentation with wiring, setup, and usage instructions

README.md

@@ -1,3 +1,332 @@
-# esp32-bluetooth-relay
+# ESP32 8-Channel Bluetooth Relay Controller
 
-ESP32 8-channel Bluetooth-controlled power relay with mobile app support
+A comprehensive ESP32-based 8-channel relay controller with Bluetooth connectivity for wireless control via smartphone or computer.
+
+## Features
+
+- ✅ Control 8 independent relays via Bluetooth
+- ✅ Simple text-based command protocol
+- ✅ Individual relay on/off/toggle control
+- ✅ All relays on/off commands
+- ✅ Status query for all relays
+- ✅ Persistent state memory (remembers relay states after reboot)
+- ✅ Easy integration with mobile apps (Serial Bluetooth Terminal, etc.)
+- ✅ Compatible with Home Assistant via Bluetooth Serial integration
+
+## Hardware Requirements
+
+### Essential Components
+
+1. **ESP32 Development Board**
+   - Any ESP32 board with Bluetooth (ESP32-DevKitC, ESP32-WROOM, etc.)
+   - Minimum 8 GPIO pins available
+
+2. **8-Channel Relay Module**
+   - 5V or 3.3V trigger relay module
+   - Recommended: Active LOW trigger relays
+   - Options:
+     - Single 8-channel relay board
+     - Two 4-channel relay boards
+     - Individual relay modules
+
+3. **Power Supply**
+   - 5V power supply for ESP32 (USB or external)
+   - Separate power for relay coils if using high-current loads
+   - Recommended: 5V 2A+ power supply
+
+4. **Wiring Components**
+   - Jumper wires (male-to-male, male-to-female)
+   - Breadboard (optional for prototyping)
+   - Terminal blocks (for AC/DC load connections)
+
+### Optional Components
+
+- Enclosure/project box
+- Status LEDs (already on most relay modules)
+- Fuse holders for safety
+- PCB for permanent installation
+
+## Wiring Diagram
+
+### GPIO Pin Assignments (Default)
+
+| Relay # | ESP32 GPIO | Relay Module Pin |
+|---------|------------|------------------|
+| Relay 1 | GPIO 13    | IN1             |
+| Relay 2 | GPIO 12    | IN2             |
+| Relay 3 | GPIO 14    | IN3             |
+| Relay 4 | GPIO 27    | IN4             |
+| Relay 5 | GPIO 26    | IN5             |
+| Relay 6 | GPIO 25    | IN6             |
+| Relay 7 | GPIO 33    | IN7             |
+| Relay 8 | GPIO 32    | IN8             |
+
+### Power Connections
+
+```
+ESP32                     8-Channel Relay Module
+-----                     ----------------------
+GND    -----------------> GND
+5V     -----------------> VCC (or separate 5V supply)
+
+GPIO13 -----------------> IN1
+GPIO12 -----------------> IN2
+GPIO14 -----------------> IN3
+GPIO27 -----------------> IN4
+GPIO26 -----------------> IN5
+GPIO25 -----------------> IN6
+GPIO33 -----------------> IN7
+GPIO32 -----------------> IN8
+```
+
+### Load Connections (Per Relay)
+
+Each relay has three terminals:
+- **COM (Common)**: Connect to power source
+- **NO (Normally Open)**: Connects to COM when relay is ON
+- **NC (Normally Closed)**: Connects to COM when relay is OFF
+
+**Example for controlling AC devices:**
+```
+AC Live Wire --> Relay COM
+Relay NO     --> Device Live Wire
+AC Neutral   --> Device Neutral (direct connection)
+```
+
+⚠️ **WARNING**: Working with AC power is dangerous! Only attempt if you're qualified. Consider using DC loads for initial testing.
+
+## Software Setup
+
+### Arduino IDE Setup
+
+1. **Install ESP32 Board Support**
+   - Open Arduino IDE
+   - Go to File → Preferences
+   - Add to "Additional Board Manager URLs":
+     ```
+     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+     ```
+   - Go to Tools → Board → Board Manager
+   - Search for "ESP32" and install
+
+2. **Configure Board Settings**
+   - Board: "ESP32 Dev Module" (or your specific board)
+   - Upload Speed: 115200
+   - Flash Frequency: 80MHz
+   - Partition Scheme: "Default 4MB with spiffs"
+
+3. **Upload the Code**
+   - Open `esp32_bluetooth_relay.ino`
+   - Select your ESP32 board and COM port
+   - Click Upload
+
+### PlatformIO Setup (Alternative)
+
+If using PlatformIO:
+
+```ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+lib_deps = 
+    BluetoothSerial
+```
+
+## Usage
+
+### Connecting via Bluetooth
+
+1. **Power on the ESP32**
+   - The device will appear as "ESP32-Relay-8CH"
+
+2. **Pair the Device**
+   - On your phone/computer, search for Bluetooth devices
+   - Connect to "ESP32-Relay-8CH"
+   - Default PIN: 1234 (if prompted)
+
+3. **Use a Serial Bluetooth Terminal**
+   - Android: "Serial Bluetooth Terminal" app
+   - iOS: "Bluetooth Terminal" app
+   - Windows: PuTTY with Bluetooth COM port
+   - Linux: `bluetoothctl` and `minicom`
+
+### Command Reference
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `ON1` - `ON8` | Turn on specific relay | `ON1` turns on Relay 1 |
+| `OFF1` - `OFF8` | Turn off specific relay | `OFF5` turns off Relay 5 |
+| `TOGGLE1` - `TOGGLE8` | Toggle specific relay | `TOGGLE3` toggles Relay 3 |
+| `ALL_ON` | Turn all relays on | `ALL_ON` |
+| `ALL_OFF` | Turn all relays off | `ALL_OFF` |
+| `STATUS` | Get status of all relays | `STATUS` |
+| `HELP` | Show available commands | `HELP` |
+
+Commands are **case-insensitive** and should be sent with a newline character.
+
+### Example Session
+
+```
+> STATUS
+=== Relay Status ===
+Relay 1: OFF
+Relay 2: OFF
+Relay 3: ON
+Relay 4: OFF
+Relay 5: OFF
+Relay 6: OFF
+Relay 7: OFF
+Relay 8: OFF
+===================
+
+> ON1
+Relay 1 is now ON
+
+> TOGGLE3
+Relay 3 is now OFF
+
+> ALL_ON
+All relays turned ON
+```
+
+## Customization
+
+### Changing GPIO Pins
+
+Edit the `relayPins` array in the code:
+
+```cpp
+const int relayPins[8] = {13, 12, 14, 27, 26, 25, 33, 32};
+```
+
+### Changing Bluetooth Device Name
+
+Edit the `deviceName` constant:
+
+```cpp
+const char* deviceName = "YourCustomName";
+```
+
+### Changing Relay Names
+
+Edit the `relayNames` array:
+
+```cpp
+const char* relayNames[8] = {
+  "Living Room", "Bedroom", "Kitchen", "Bathroom",
+  "Garden", "Garage", "Office", "Workshop"
+};
+```
+
+### Active HIGH vs Active LOW Relays
+
+Most relay modules are **active LOW** (relay turns ON when GPIO is LOW). If you have active HIGH relays, change:
+
+```cpp
+// In setRelay() function, change:
+digitalWrite(relayPins[relayIndex], state ? LOW : HIGH);
+// to:
+digitalWrite(relayPins[relayIndex], state ? HIGH : LOW);
+```
+
+## Home Assistant Integration
+
+### Method 1: Bluetooth Serial Integration
+
+1. Install the Bluetooth Serial integration in Home Assistant
+2. Add to `configuration.yaml`:
+
+```yaml
+bluetooth_serial:
+  - address: "XX:XX:XX:XX:XX:XX"  # ESP32 MAC address
+    name: "ESP32 Relay Controller"
+    
+switch:
+  - platform: template
+    switches:
+      relay_1:
+        friendly_name: "Relay 1"
+        turn_on:
+          service: bluetooth_serial.send
+          data:
+            address: "XX:XX:XX:XX:XX:XX"
+            message: "ON1\n"
+        turn_off:
+          service: bluetooth_serial.send
+          data:
+            address: "XX:XX:XX:XX:XX:XX"
+            message: "OFF1\n"
+```
+
+### Method 2: ESPHome (Alternative Firmware)
+
+For better Home Assistant integration, consider using ESPHome firmware instead. (Separate implementation recommended)
+
+## Troubleshooting
+
+### Bluetooth Not Showing Up
+- Ensure Bluetooth is enabled in your ESP32 build
+- Check if device is already paired with another device
+- Try restarting the ESP32
+
+### Relays Not Switching
+- Verify wiring connections
+- Check if relay module requires 5V and you're providing it
+- Test with a multimeter
+- Verify GPIO pins are correctly defined
+
+### Intermittent Connection
+- Move closer to ESP32
+- Check power supply stability
+- Ensure no interference from other Bluetooth devices
+
+### Relays Switching Opposite Direction
+- Your relay module might be active HIGH instead of active LOW
+- See "Active HIGH vs Active LOW Relays" section above
+
+## Safety Warnings
+
+⚠️ **ELECTRICAL SAFETY**
+- Never work on AC wiring while powered
+- Use proper insulation and enclosures
+- Follow local electrical codes
+- Consider hiring a licensed electrician for permanent installations
+- Test with low voltage DC loads first
+
+⚠️ **RELAY RATINGS**
+- Don't exceed relay current/voltage ratings
+- Use appropriate fuses
+- Account for inductive loads (motors, transformers)
+
+## License
+
+This project is open source and available under the MIT License.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## Support
+
+For questions or issues:
+- Open an issue on the repository
+- Check existing issues for solutions
+- Consult ESP32 and Arduino forums
+
+## Future Enhancements
+
+Potential additions:
+- [ ] Web interface (ESP32 web server)
+- [ ] MQTT support for Home Assistant
+- [ ] Scheduling/timers
+- [ ] Mobile app development
+- [ ] WiFi connectivity option
+- [ ] Scene/macro support
+- [ ] Energy monitoring
+
+---
+
+**Version:** 1.0.0  
+**Last Updated:** December 2025