alexei.dolgolyov
7f613df362
Some checks failed
Validate / validate (push) Failing after 9s
- Replace segment-based calibration with core parameters (leds_top/right/bottom/left); segments are now derived at runtime via lookup tables - Fix clockwise/counterclockwise edge traversal order for all 8 start_position/layout combinations (e.g. bottom_left+clockwise now correctly goes up-left first) - Add pixel layout preview overlay with color-coded edges, LED index labels, direction arrows, and start position marker - Move "Add New Device" form into a modal dialog triggered by "+" button - Add display index selector to device settings modal - Migrate from requirements.txt to pyproject.toml for dependency management - Update Dockerfile and docs to use `pip install .` Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
192 lines
4.4 KiB
Markdown
192 lines
4.4 KiB
Markdown
# 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 .
|
|
|
|
# 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)
|