wled-screen-controller-mixed/server/README.md

WLED Screen Controller - Server

High-performance FastAPI server that captures screen content and controls WLED devices for ambient lighting.

Overview

The server component provides:

• 🎯 Real-time Screen Capture - Multi-monitor support with configurable FPS
• 🎨 Advanced Processing - Border pixel extraction with color correction
• 🔧 Flexible Calibration - Map screen edges to any LED layout
• 🌐 REST API - Complete control via 17 REST endpoints
• 💾 Persistent Storage - JSON-based device and configuration management
• 📊 Metrics & Monitoring - Real-time FPS, status, and performance data

Quick Start

Option 1: Docker (Recommended)

# Start server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop server
docker-compose down

Server runs on: http://localhost:8080

Option 2: Python

# Create virtual environment
python -m venv venv

# Activate
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

# Set PYTHONPATH
export PYTHONPATH=$(pwd)/src  # Linux/Mac
set PYTHONPATH=%CD%\src       # Windows

# Run server
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080

Installation

Requirements

• Python 3.11+ (for Python installation)
• Docker & Docker Compose (for Docker installation)
• WLED device on your network

See ../INSTALLATION.md for comprehensive installation guide.

Configuration

Configuration File

Edit config/default_config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  log_level: "INFO"

processing:
  default_fps: 30        # Target frames per second
  max_fps: 60           # Maximum allowed FPS
  border_width: 10      # Pixels to sample from edge

wled:
  timeout: 5            # Connection timeout (seconds)
  retry_attempts: 3     # Number of retries

storage:
  devices_file: "data/devices.json"

logging:
  format: "json"
  file: "logs/wled_controller.log"

Environment Variables

# Server configuration
export WLED_SERVER__HOST="0.0.0.0"
export WLED_SERVER__PORT=8080
export WLED_SERVER__LOG_LEVEL="INFO"

# Processing configuration
export WLED_PROCESSING__DEFAULT_FPS=30
export WLED_PROCESSING__BORDER_WIDTH=10

# WLED configuration
export WLED_WLED__TIMEOUT=5

Usage

WLED Device Setup

Important: Configure your WLED device using the official WLED web interface before connecting it to this controller:

1. Access WLED Interface: Open http://[wled-ip] in your browser
2. Configure Device Settings:
   • Set LED count and type
   • Configure brightness, color order, and power limits
   • Set up segments if needed
   • Configure effects and presets

This controller only sends pixel color data - it does not manage WLED settings like brightness, effects, or segments. All WLED device configuration should be done through the official WLED interface.

API Documentation

• Web UI: http://localhost:8080 (recommended for device management)
• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

Quick Example

# 1. Add device
curl -X POST http://localhost:8080/api/v1/devices \
  -H "Content-Type: application/json" \
  -d '{"name":"Living Room","url":"http://192.168.1.100","led_count":150}'

# 2. Start processing
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start

# 3. Check status
curl http://localhost:8080/api/v1/devices/{device_id}/state

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=wled_controller --cov-report=html

# Run specific test
pytest tests/test_screen_capture.py -v

Development

Project Structure

src/wled_controller/
├── main.py              # FastAPI application
├── config.py            # Configuration
├── api/                 # API routes
├── core/                # Core functionality
│   ├── screen_capture.py
│   ├── wled_client.py
│   ├── calibration.py
│   └── processor_manager.py
├── storage/             # Data persistence
└── utils/               # Utilities

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

License

MIT - see ../LICENSE

Support

• 📖 Full Documentation
• 🐛 Issues