From 7ab41c17ce8ee854373d04cc7935dd313908e12b Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Mon, 15 Dec 2025 16:25:58 +1100
Subject: [PATCH] Add ESP32 Bluetooth relay integration documentation to README

---
 README.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index efbff8e..edfb19e 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,12 @@ A sophisticated NFC-based video player system designed for an immersive drive-in
 - **Unattend Mode**: Automatic cycling through content (3 trailers + 1 movie pattern)
 - **Global NFC Capture**: Works even when video is fullscreen
 - **Multi-Device Support**: Control from desktop, mobile, or tablet
+- **ESP32 Bluetooth Relay Integration**: Automated theatre control (lights, speakers, effects)
+  - Auto-dim lights when movies start
+  - Power speakers on/off automatically
+  - Control up to 8 relay channels via Bluetooth
+  - Web dashboard relay controls
+  - See `docs/ESP32_RELAY_INTEGRATION.md` for setup guide
 
 ## 🚀 Quick Start
 
@@ -56,9 +62,13 @@ moonlight-drive-in/
 ├── enhanced_debug_console.py        # Enhanced debug with web support
 ├── web_interface.py                 # Flask web dashboard
 ├── web_mpv_main.py                  # Web-enabled entry point
+├── esp32_relay_controller.py        # ESP32 Bluetooth relay interface
+├── theatre_automation.py            # Theatre automation logic
 ├── *.bat                            # Windows launcher scripts
 ├── dashboard.html                   # Web dashboard interface
 ├── validate_videos.py               # Validation tool
+├── docs/
+│   └── ESP32_RELAY_INTEGRATION.md   # Relay integration guide
 └── videos/
     ├── trailers/                    # Trailer video files
     ├── specific/                    # Single movie files
@@ -93,6 +103,7 @@ Access the web dashboard for:
 - 🎬 Manual video selection
 - 📁 Folder management
 - ⚙️ System configuration
+- 💡 Theatre automation (relay controls)
 
 ### Debug Console
 
@@ -105,6 +116,30 @@ The desktop debug console provides:
 
 ## 🛠️ Advanced Features
 
+### ESP32 Theatre Automation
+
+Control theatre equipment automatically via Bluetooth relay controller:
+
+**Features:**
+- Auto-dim house lights when movies start
+- Auto-power speakers during playback
+- Manual relay controls via web interface
+- Programmable lighting effects
+- Closing/intermission sequences
+
+**Setup:**
+1. Build ESP32 relay controller (see separate repository)
+2. Pair ESP32 with computer via Bluetooth
+3. Enable in `config.py`:
+   ```python
+   RELAY_CONFIG = {
+       'enabled': True,
+       'auto_theatre_lights': True,
+       'auto_speaker_power': True,
+   }
+   ```
+4. Full documentation in `docs/ESP32_RELAY_INTEGRATION.md`
+
 ### Folder Sequences
 
 Create multi-video sequences that play in order:
@@ -138,6 +173,7 @@ Edit `config.py` to customize:
 - Playback parameters
 - Display preferences
 - Logging levels
+- ESP32 relay automation
 
 ## 🐛 Troubleshooting
 
@@ -163,6 +199,8 @@ This checks:
 
 **Folder sequences not advancing**: Check `folder_state.json` or reset via debug console
 
+**ESP32 relay not responding**: See `docs/ESP32_RELAY_INTEGRATION.md` troubleshooting section
+
 ## 📊 System Requirements
 
 - **OS**: Windows (primary), Linux (experimental)
@@ -170,14 +208,15 @@ This checks:
 - **MPV**: Required for video playback
 - **NFC Reader**: ACS ACR122 or compatible
 - **Network**: For web interface access
+- **ESP32** (optional): For theatre automation
 
 ## 🔮 Planned Features
 
 - LEGO Dimensions Portal integration (7-zone NFC reading)
-- Bluetooth LED controller integration
 - Expanded capacity beyond 64 movies
 - Additional automation patterns
 - Enhanced gallery interfaces
+- Advanced lighting effects and sequences
 
 ## 📝 License