moonlight-drive-in/docs/RELAY_CONFIG_EXAMPLES.md

ESP32 Relay Configuration Examples

Example configurations for integrating ESP32 relay controller with Moonlight Drive-In.

Basic Configuration

Add this to your config.py:

# 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:

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:

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:

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:

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:

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:

# ============================================
# 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

# 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

# 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

# Try explicit port specification
RELAY_CONFIG = {
    'enabled': True,
    'relay_port': 'COM4',              # Change to your actual port
    # ... rest of config
}

Debugging

# 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

# 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:

   python esp32_relay_controller.py
   

2. Automation Test:

   python theatre_automation.py
   

3. Full Integration Test:

   # 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