# ESP32 Bluetooth Relay Theatre Automation

**Date:** 2025-12-15
**Project:** moonlight-drive-in
**Status:** resolved
**Tags:** esp32, bluetooth, relay, pyserial, theatre-automation, lighting

## Context
Jess wanted the drive-in to control physical power — lights and other theatre effects — alongside video playback. An ESP32 8-channel Bluetooth relay board (separate repo `esp32-bluetooth-relay`) was built, and this session added the Python side so the player can switch relays as part of a show.

## Key Decisions
- **ESP32 relay over Bluetooth serial** (via `pyserial` on the Windows host's BT COM port) — cheap, no extra network config, and independent of the LAN.
- **Separate `theatre_automation.py` layer** between the player and the relay driver — keeps show logic (what switches when) out of the low-level relay module.
- **Relay control optional** — the player still runs if the relay isn't connected.
- The earlier KAIYU Bluetooth LED controller route had been abandoned; smart plugs / USB relay boards were researched as alternatives, and the ESP32 relay was chosen.

## Technical Details
- `esp32_relay_controller.py` — relay driver (8 channels) over serial.
- `theatre_automation.py` — maps player events to relay actions.
- `test_relay.bat` — connection test script.
- Dependency: `pyserial`.
- Relay configuration examples and a reference guide are in the repo docs.

## Code Changes
- `esp32_relay_controller.py` — new.
- `theatre_automation.py` — new.
- `test_relay.bat` — new.
- Python requirements — added `pyserial`.
- `README.md` + integration guide + relay config examples.

## Open Questions / Next Steps
- Confirm which relay channels are wired to which theatre devices and record the mapping in the relay config.

## Artifacts
- `412fc3b` — Add ESP32 Bluetooth relay controller Python module
- `bc3ab2f` — Add theatre automation integration for ESP32 relay control
- Related repo: https://gitea.hideawaygaming.com.au/jessikitty/esp32-bluetooth-relay