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)

```bash
# 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

```bash
# 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](../INSTALLATION.md) for comprehensive installation guide.

## Configuration

### Configuration File

Edit `config/default_config.yaml`:

```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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/
```

## License

MIT - see [../LICENSE](../LICENSE)

## Support

- 📖 [Full Documentation](../docs/)
- 🐛 [Issues](https://github.com/yourusername/wled-screen-controller/issues)