Add relay configuration examples and reference guide
This commit is contained in:
345
docs/RELAY_CONFIG_EXAMPLES.md
Normal file
345
docs/RELAY_CONFIG_EXAMPLES.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user