Initial commit: WLED Screen Controller with FastAPI server and Home Assistant integration

This is a complete WLED ambient lighting controller that captures screen border pixels and sends them to WLED devices for immersive ambient lighting effects. ## Server Features: - FastAPI-based REST API with 17+ endpoints - Real-time screen capture with multi-monitor support - Advanced LED calibration system with visual GUI - API key authentication with labeled tokens - Per-device brightness control (0-100%) - Configurable FPS (1-60), border width, and color correction - Persistent device storage (JSON-based) - Comprehensive Web UI with dark/light themes - Docker support with docker-compose - Windows monitor name detection via WMI (shows "LG ULTRAWIDE" etc.) ## Web UI Features: - Device management (add, configure, remove WLED devices) - Real-time status monitoring with FPS metrics - Settings modal for device configuration - Visual calibration GUI with edge testing - Brightness slider per device - Display selection with friendly monitor names - Token-based authentication with login/logout - Responsive button layout ## Calibration System: - Support for any LED strip layout (clockwise/counterclockwise) - 4 starting position options (corners) - Per-edge LED count configuration - Visual preview with starting position indicator - Test buttons to light up individual edges - Smart LED ordering based on start position and direction ## Home Assistant Integration: - Custom HACS integration - Switch entities for processing control - Sensor entities for status and FPS - Select entities for display selection - Config flow for easy setup - Auto-discovery of devices from server ## Technical Stack: - Python 3.11+ - FastAPI + uvicorn - mss (screen capture) - httpx (async WLED client) - Pydantic (validation) - WMI (Windows monitor detection) - Structlog (logging) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-06 16:38:27 +03:00
commit d471a40234
57 changed files with 9726 additions and 0 deletions
--- a/custom_components/wled_screen_controller/README.md
+++ b/custom_components/wled_screen_controller/README.md
@@ -0,0 +1,214 @@
+# WLED Screen Controller - Home Assistant Integration
+
+Native Home Assistant integration for WLED Screen Controller with full HACS support.
+
+## Overview
+
+This integration connects Home Assistant to the WLED Screen Controller server, providing:
+
+- 🎛️ **Switch Entities** - Turn processing on/off per device
+- 📊 **Sensor Entities** - Monitor FPS, status, and frame count
+- 🖥️ **Select Entities** - Choose which display to capture
+- 🔄 **Auto-Discovery** - Devices appear automatically
+- 📦 **HACS Compatible** - Install directly from HACS
+- ⚙️ **Config Flow** - Easy setup through UI
+
+## Installation
+
+### Method 1: HACS (Recommended)
+
+1. **Install HACS** if you haven't already:
+   - Visit https://hacs.xyz/docs/setup/download
+
+2. **Add Custom Repository:**
+   - Open HACS in Home Assistant
+   - Click the menu (⋮) → Custom repositories
+   - Add URL: `https://github.com/yourusername/wled-screen-controller`
+   - Category: **Integration**
+   - Click **Add**
+
+3. **Install Integration:**
+   - In HACS, search for "WLED Screen Controller"
+   - Click **Download**
+   - Restart Home Assistant
+
+4. **Configure:**
+   - Go to Settings → Devices & Services
+   - Click **+ Add Integration**
+   - Search for "WLED Screen Controller"
+   - Enter your server URL (e.g., `http://192.168.1.100:8080`)
+   - Click **Submit**
+
+### Method 2: Manual Installation
+
+1. **Download:**
+   ```bash
+   cd /config  # Your Home Assistant config directory
+   mkdir -p custom_components
+   ```
+
+2. **Copy Files:**
+   Copy the entire `custom_components/wled_screen_controller` folder to your Home Assistant `custom_components/` directory.
+
+3. **Restart Home Assistant**
+
+4. **Configure:**
+   - Settings → Devices & Services → Add Integration
+   - Search for "WLED Screen Controller"
+
+## Configuration
+
+### Initial Setup
+
+When adding the integration, you'll be prompted for:
+
+- **Name**: Friendly name for the integration (default: "WLED Screen Controller")
+- **Server URL**: URL of your WLED Screen Controller server (e.g., `http://192.168.1.100:8080`)
+
+The integration will automatically:
+- Verify connection to the server
+- Discover all configured WLED devices
+- Create entities for each device
+
+### Entities Created
+
+For each WLED device, the following entities are created:
+
+#### Switch Entities
+
+**`switch.{device_name}_processing`**
+- Controls processing on/off for the device
+- Attributes:
+  - `device_id`: Internal device ID
+  - `fps_target`: Target FPS
+  - `fps_actual`: Current FPS
+  - `display_index`: Active display
+  - `frames_processed`: Total frames
+  - `errors_count`: Error count
+  - `uptime_seconds`: Processing uptime
+
+#### Sensor Entities
+
+**`sensor.{device_name}_fps`**
+- Current FPS value
+- Unit: FPS
+- Attributes:
+  - `target_fps`: Target FPS setting
+
+**`sensor.{device_name}_status`**
+- Processing status
+- States: `processing`, `idle`, `unavailable`, `unknown`
+
+**`sensor.{device_name}_frames_processed`**
+- Total frames processed counter
+- Continuously increasing while processing
+
+#### Select Entities
+
+**`select.{device_name}_display`**
+- Select which display to capture
+- Options: `Display 0`, `Display 1`, etc.
+- Changes take effect immediately
+
+## Usage Examples
+
+### Basic Automation
+
+Turn on processing when TV turns on:
+
+```yaml
+automation:
+  - alias: "Auto Start WLED with TV"
+    trigger:
+      - platform: state
+        entity_id: media_player.living_room_tv
+        to: "on"
+    action:
+      - service: switch.turn_on
+        target:
+          entity_id: switch.living_room_wled_processing
+
+  - alias: "Auto Stop WLED with TV"
+    trigger:
+      - platform: state
+        entity_id: media_player.living_room_tv
+        to: "off"
+    action:
+      - service: switch.turn_off
+        target:
+          entity_id: switch.living_room_wled_processing
+```
+
+### Lovelace UI Examples
+
+#### Simple Card
+
+```yaml
+type: entities
+title: WLED Screen Controller
+entities:
+  - entity: switch.living_room_wled_processing
+  - entity: sensor.living_room_wled_fps
+  - entity: sensor.living_room_wled_status
+  - entity: select.living_room_wled_display
+```
+
+#### Advanced Card
+
+```yaml
+type: vertical-stack
+cards:
+  - type: entity
+    entity: switch.living_room_wled_processing
+    name: Ambient Lighting
+    icon: mdi:television-ambient-light
+
+  - type: conditional
+    conditions:
+      - entity: switch.living_room_wled_processing
+        state: "on"
+    card:
+      type: entities
+      entities:
+        - entity: sensor.living_room_wled_fps
+          name: Current FPS
+        - entity: sensor.living_room_wled_frames_processed
+          name: Frames Processed
+        - entity: select.living_room_wled_display
+          name: Display Selection
+```
+
+## Troubleshooting
+
+### Integration Not Appearing
+
+1. Check HACS installation
+2. Clear browser cache
+3. Restart Home Assistant
+4. Check logs: Settings → System → Logs
+
+### Connection Errors
+
+1. Verify server is running:
+   ```bash
+   curl http://YOUR_SERVER_IP:8080/health
+   ```
+
+2. Check firewall settings
+3. Ensure Home Assistant can reach server
+4. Try http:// not https://
+
+### Entities Not Updating
+
+1. Check coordinator logs
+2. Verify server has devices
+3. Restart integration
+
+## Support
+
+- 📖 [Full Documentation](../../INSTALLATION.md)
+- 🐛 [Report Issues](https://github.com/yourusername/wled-screen-controller/issues)
+
+## License
+
+MIT License - see [../../LICENSE](../../LICENSE)