Add relay configuration examples and reference guide

docs/RELAY_CONFIG_EXAMPLES.md

@@ -0,0 +1,345 @@
+# ESP32 Relay Configuration Examples
+
+Example configurations for integrating ESP32 relay controller with Moonlight Drive-In.
+
+## Basic Configuration
+
+Add this to your `config.py`:
+
+```python
+# ESP32 Bluetooth Relay Controller Configuration
+RELAY_CONFIG = {
+    # Enable/disable relay automation
+    'enabled': True,
+    
+    # Automatic theatre lighting control
+    'auto_theatre_lights': True,      # Auto dim lights during movies
+    'light_dim_delay': 5,              # Seconds before dimming (default 5)
+    
+    # Automatic speaker power control
+    'auto_speaker_power': True,        # Auto power speakers during playback
+    
+    # Serial port configuration
+    # None = auto-detect (recommended)
+    # Or specify: 'COM4' (Windows) or '/dev/rfcomm0' (Linux)
+    'relay_port': None,
+    
+    # Relay function mapping (relay numbers 1-8)
+    # Customize these to match your wiring
+    'relay_mapping': {
+        'HOUSE_LIGHTS': 1,
+        'SCREEN_LIGHTS': 2,
+        'MARQUEE_LIGHTS': 3,
+        'SPEAKER_POWER': 4,
+        'PROJECTOR_POWER': 5,
+        'EFFECT_LIGHTS': 6,
+        'CONCESSION_LIGHTS': 7,
+        'PARKING_LIGHTS': 8,
+    }
+}
+```
+
+## Minimal Configuration (Manual Control Only)
+
+For manual relay control via web interface only:
+
+```python
+RELAY_CONFIG = {
+    'enabled': True,
+    'auto_theatre_lights': False,     # Disable auto light control
+    'auto_speaker_power': False,      # Disable auto speaker control
+    'relay_port': None,
+}
+```
+
+## Custom Relay Mapping
+
+If your relays are wired differently:
+
+```python
+RELAY_CONFIG = {
+    'enabled': True,
+    'auto_theatre_lights': True,
+    'auto_speaker_power': True,
+    'light_dim_delay': 3,              # Faster dimming
+    
+    # Custom wiring
+    'relay_mapping': {
+        'HOUSE_LIGHTS': 2,             # Changed from relay 1 to 2
+        'SCREEN_LIGHTS': 1,             # Changed from relay 2 to 1
+        'MARQUEE_LIGHTS': 3,
+        'SPEAKER_POWER': 4,
+        'PROJECTOR_POWER': 5,
+        'EFFECT_LIGHTS': 6,
+        'CONCESSION_LIGHTS': 7,
+        'PARKING_LIGHTS': 8,
+    }
+}
+```
+
+## Linux Configuration
+
+For Linux systems with Bluetooth serial:
+
+```python
+RELAY_CONFIG = {
+    'enabled': True,
+    'auto_theatre_lights': True,
+    'auto_speaker_power': True,
+    
+    # Specify the RFCOMM device
+    'relay_port': '/dev/rfcomm0',      # Or /dev/ttyUSB0
+    
+    'relay_mapping': {
+        # ... same as above
+    }
+}
+```
+
+## Advanced Timing Configuration
+
+Customize automation timing:
+
+```python
+RELAY_CONFIG = {
+    'enabled': True,
+    'auto_theatre_lights': True,
+    'auto_speaker_power': True,
+    
+    # Longer delay before dimming
+    'light_dim_delay': 10,             # Wait 10 seconds before dimming
+    
+    # For testing/debugging
+    'relay_port': 'COM4',              # Explicitly set port
+    
+    'relay_mapping': {
+        # ... as needed
+    }
+}
+```
+
+## Fewer Relays Configuration
+
+If using only 4 relays instead of 8:
+
+```python
+RELAY_CONFIG = {
+    'enabled': True,
+    'auto_theatre_lights': True,
+    'auto_speaker_power': True,
+    
+    # Map only the relays you're actually using
+    'relay_mapping': {
+        'HOUSE_LIGHTS': 1,
+        'SCREEN_LIGHTS': 2,
+        'SPEAKER_POWER': 3,
+        'EFFECT_LIGHTS': 4,
+        # Relays 5-8 not configured (unused)
+    }
+}
+```
+
+## Complete Example with All Settings
+
+Full configuration with all options:
+
+```python
+# ============================================
+# ESP32 Bluetooth Relay Controller
+# ============================================
+
+RELAY_CONFIG = {
+    # Master enable/disable
+    'enabled': True,
+    
+    # Automation features
+    'auto_theatre_lights': True,       # Auto control lights
+    'auto_speaker_power': True,        # Auto control speakers
+    'light_dim_delay': 5,              # Delay before dimming (seconds)
+    
+    # Connection settings
+    'relay_port': None,                # Auto-detect (or specify COM4, etc.)
+    
+    # Relay assignments
+    # Adjust these numbers to match your physical wiring
+    'relay_mapping': {
+        'HOUSE_LIGHTS': 1,             # Main overhead lights
+        'SCREEN_LIGHTS': 2,            # Screen border/backlight
+        'MARQUEE_LIGHTS': 3,           # Entrance sign lights
+        'SPEAKER_POWER': 4,            # Audio amplifier power
+        'PROJECTOR_POWER': 5,          # Video projector
+        'EFFECT_LIGHTS': 6,            # Special effects/RGB
+        'CONCESSION_LIGHTS': 7,        # Snack bar area
+        'PARKING_LIGHTS': 8,           # Outdoor parking area
+    },
+    
+    # Advanced options (optional)
+    'reconnect_attempts': 3,           # Auto-reconnect tries
+    'command_timeout': 2.0,            # Command timeout (seconds)
+}
+
+# ============================================
+# Usage Examples
+# ============================================
+
+# Enable automation
+# - Lights dim 5 seconds after movie starts
+# - Speakers power on during playback
+# - Lights come back up when movie ends
+
+# Disable automation (manual control only)
+# Set auto_theatre_lights and auto_speaker_power to False
+
+# Custom timing
+# Increase light_dim_delay for longer warning before dimming
+# (Gives audience more time to get seated)
+
+# Manual port specification
+# Use 'relay_port' if auto-detection doesn't work
+# Windows: 'COM3', 'COM4', etc.
+# Linux: '/dev/rfcomm0', '/dev/ttyUSB0', etc.
+```
+
+## Integration Code Examples
+
+### Access Relay Controller in Your Code
+
+```python
+# In mpv_seamless_player.py or other module
+from theatre_automation import TheatreAutomation, RelayFunction
+import config
+
+# Initialize
+self.theatre = None
+if config.RELAY_CONFIG.get('enabled', False):
+    self.theatre = TheatreAutomation(config.RELAY_CONFIG)
+    self.theatre.connect()
+
+# Before playing movie
+if self.theatre:
+    self.theatre.movie_starting(is_trailer=False)
+
+# After movie ends
+if self.theatre:
+    self.theatre.movie_ended(is_trailer=False)
+
+# Manual control
+if self.theatre:
+    self.theatre.set_relay(RelayFunction.HOUSE_LIGHTS, False)
+    
+# Clean shutdown
+if self.theatre:
+    self.theatre.closing_sequence()
+    self.theatre.disconnect()
+```
+
+### Web API Integration
+
+```python
+# In web_interface.py
+
+from theatre_automation import TheatreAutomation, RelayFunction
+import config
+
+# Initialize at app startup
+theatre = None
+if config.RELAY_CONFIG.get('enabled'):
+    theatre = TheatreAutomation(config.RELAY_CONFIG)
+    theatre.connect()
+
+# Add routes
+@app.route('/api/relay/<function_name>/<state>')
+def control_relay(function_name, state):
+    if theatre and theatre.connected:
+        func = RelayFunction[function_name.upper()]
+        state_bool = (state.lower() == 'on')
+        theatre.set_relay(func, state_bool)
+        return jsonify({'success': True})
+    return jsonify({'error': 'Not connected'}), 503
+```
+
+## Troubleshooting Configurations
+
+### Connection Issues
+
+```python
+# Try explicit port specification
+RELAY_CONFIG = {
+    'enabled': True,
+    'relay_port': 'COM4',              # Change to your actual port
+    # ... rest of config
+}
+```
+
+### Debugging
+
+```python
+# Enable detailed logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Test connection separately
+from esp32_relay_controller import ESP32RelayController
+relay = ESP32RelayController()
+relay.connect('COM4')  # Your port
+```
+
+### Timing Issues
+
+```python
+# Increase delays if relays switch too quickly
+RELAY_CONFIG = {
+    'enabled': True,
+    'light_dim_delay': 10,             # Longer delay
+    'command_timeout': 5.0,            # Longer timeout
+    # ... rest of config
+}
+```
+
+## Testing Your Configuration
+
+1. **Basic Connection Test**:
+   ```bash
+   python esp32_relay_controller.py
+   ```
+
+2. **Automation Test**:
+   ```bash
+   python theatre_automation.py
+   ```
+
+3. **Full Integration Test**:
+   ```bash
+   # With relay automation enabled in config
+   python start_web_player.bat
+   ```
+
+## Quick Reference
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | False | Master enable switch |
+| `auto_theatre_lights` | True | Auto dim lights |
+| `auto_speaker_power` | True | Auto power speakers |
+| `light_dim_delay` | 5 | Delay before dimming (seconds) |
+| `relay_port` | None | Serial port (auto-detect if None) |
+| `relay_mapping` | See above | Relay number assignments |
+
+## Safety Notes
+
+- Test with non-critical loads first
+- Verify wiring before enabling automation
+- Keep manual overrides accessible
+- Use appropriate fuses for all loads
+- Follow local electrical codes
+
+---
+
+**See Also:**
+- `docs/ESP32_RELAY_INTEGRATION.md` - Complete integration guide
+- `esp32_relay_controller.py` - Low-level controller code
+- `theatre_automation.py` - High-level automation logic
+- ESP32 firmware repository - Hardware setup
+
+**Version:** 1.0  
+**Last Updated:** December 2025