alexei.dolgolyov
02cd9d519c
Lint & Test / test (push) Successful in 1m56s
- Rename Python package: wled_controller -> ledgrab - Rename env var prefix: WLED_ -> LEDGRAB_ (with auto-migration for old vars) - Rename localStorage key: wled_api_key -> ledgrab_api_key (with migration) - Rename HA integration domain: wled_screen_controller -> ledgrab - Update all imports, build scripts, Docker, installer, config, docs - Remove HA integration (moved to ledgrab-haos-integration repo) - Remove hacs.json (belongs in HA repo now) - Add startup warning for users with old WLED_ env vars - All tests pass (715/715), ruff clean, tsc clean, frontend builds
192 lines
4.3 KiB
Markdown
192 lines
4.3 KiB
Markdown
# LedGrab - 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 25+ 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 ledgrab.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/ledgrab.log"
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Server configuration
|
|
export LEDGRAB_SERVER__HOST="0.0.0.0"
|
|
export LEDGRAB_SERVER__PORT=8080
|
|
export LEDGRAB_SERVER__LOG_LEVEL="INFO"
|
|
|
|
# Processing configuration
|
|
export LEDGRAB_PROCESSING__DEFAULT_FPS=30
|
|
export LEDGRAB_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=ledgrab --cov-report=html
|
|
|
|
# Run specific test
|
|
pytest tests/test_screen_capture.py -v
|
|
```
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/ledgrab/
|
|
├── 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://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/issues)
|