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>

server/src/wled_controller/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Utility functions and helpers."""
+
+from .logger import setup_logging, get_logger
+from .monitor_names import get_monitor_names, get_monitor_name
+
+__all__ = ["setup_logging", "get_logger", "get_monitor_names", "get_monitor_name"]

server/src/wled_controller/utils/logger.py

@@ -0,0 +1,86 @@
+"""Logging configuration and setup."""
+
+import logging
+import sys
+from pathlib import Path
+from logging.handlers import RotatingFileHandler
+
+import structlog
+from pythonjsonlogger import jsonlogger
+
+from wled_controller.config import get_config
+
+
+def setup_logging() -> None:
+    """Configure structured logging for the application."""
+    config = get_config()
+
+    # Ensure log directory exists
+    log_path = Path(config.logging.file)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(config.server.log_level)
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(config.server.log_level)
+
+    # File handler with rotation
+    file_handler = RotatingFileHandler(
+        filename=str(log_path),
+        maxBytes=config.logging.max_size_mb * 1024 * 1024,
+        backupCount=config.logging.backup_count,
+    )
+    file_handler.setLevel(config.server.log_level)
+
+    # Configure formatter based on format setting
+    if config.logging.format == "json":
+        formatter = jsonlogger.JsonFormatter(
+            "%(asctime)s %(name)s %(levelname)s %(message)s"
+        )
+        console_handler.setFormatter(formatter)
+        file_handler.setFormatter(formatter)
+    else:
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        console_handler.setFormatter(formatter)
+        file_handler.setFormatter(formatter)
+
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(file_handler)
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.dev.set_exc_info,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer()
+            if config.logging.format == "json"
+            else structlog.dev.ConsoleRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(logging.NOTSET),
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get a configured logger instance.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Configured structlog logger
+    """
+    return structlog.get_logger(name)

server/src/wled_controller/utils/monitor_names.py

@@ -0,0 +1,79 @@
+"""Utility functions for retrieving friendly monitor/display names."""
+
+import sys
+from typing import Dict, Optional
+
+from wled_controller.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_monitor_names() -> Dict[int, str]:
+    """Get friendly names for connected monitors.
+
+    On Windows, attempts to retrieve monitor names from WMI.
+    On other platforms, returns empty dict (will fall back to generic names).
+
+    Returns:
+        Dictionary mapping display indices to friendly names
+    """
+    if sys.platform != "win32":
+        logger.debug("Monitor name detection only supported on Windows")
+        return {}
+
+    try:
+        import wmi
+
+        w = wmi.WMI(namespace="wmi")
+        monitors = w.WmiMonitorID()
+
+        monitor_names = {}
+
+        for idx, monitor in enumerate(monitors):
+            try:
+                # Extract manufacturer name
+                manufacturer = ""
+                if monitor.ManufacturerName:
+                    manufacturer = "".join(chr(c) for c in monitor.ManufacturerName if c != 0)
+
+                # Extract user-friendly name
+                user_name = ""
+                if monitor.UserFriendlyName:
+                    user_name = "".join(chr(c) for c in monitor.UserFriendlyName if c != 0)
+
+                # Build friendly name
+                if user_name:
+                    friendly_name = user_name.strip()
+                elif manufacturer:
+                    friendly_name = f"{manufacturer.strip()} Monitor"
+                else:
+                    friendly_name = f"Display {idx}"
+
+                monitor_names[idx] = friendly_name
+                logger.debug(f"Monitor {idx}: {friendly_name}")
+
+            except Exception as e:
+                logger.debug(f"Failed to parse monitor {idx} name: {e}")
+                monitor_names[idx] = f"Display {idx}"
+
+        return monitor_names
+
+    except ImportError:
+        logger.debug("WMI library not available - install with: pip install wmi")
+        return {}
+    except Exception as e:
+        logger.debug(f"Failed to retrieve monitor names via WMI: {e}")
+        return {}
+
+
+def get_monitor_name(index: int) -> str:
+    """Get friendly name for a specific monitor.
+
+    Args:
+        index: Monitor index (0-based)
+
+    Returns:
+        Friendly monitor name or generic fallback
+    """
+    monitor_names = get_monitor_names()
+    return monitor_names.get(index, f"Display {index}")