# 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