Initial commit: WLED Screen Controller with FastAPI server and Home Assistant integration
Some checks failed
Validate / validate (push) Failing after 1m6s
Some checks failed
Validate / validate (push) Failing after 1m6s
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>
This commit is contained in:
305
INSTALLATION.md
Normal file
305
INSTALLATION.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Installation Guide
|
||||
|
||||
Complete installation guide for WLED Screen Controller server and Home Assistant integration.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Server Installation](#server-installation)
|
||||
2. [Home Assistant Integration](#home-assistant-integration)
|
||||
3. [Quick Start](#quick-start)
|
||||
|
||||
---
|
||||
|
||||
## Server Installation
|
||||
|
||||
### Option 1: Python (Development/Testing)
|
||||
|
||||
**Requirements:**
|
||||
- Python 3.11 or higher
|
||||
- Windows, Linux, or macOS
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/yourusername/wled-screen-controller.git
|
||||
cd wled-screen-controller/server
|
||||
```
|
||||
|
||||
2. **Create virtual environment:**
|
||||
```bash
|
||||
python -m venv venv
|
||||
|
||||
# Windows
|
||||
venv\Scripts\activate
|
||||
|
||||
# Linux/Mac
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
3. **Install dependencies:**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Configure (optional):**
|
||||
Edit `config/default_config.yaml` to customize settings.
|
||||
|
||||
5. **Run the server:**
|
||||
```bash
|
||||
# Set PYTHONPATH
|
||||
export PYTHONPATH=$(pwd)/src # Linux/Mac
|
||||
set PYTHONPATH=%CD%\src # Windows
|
||||
|
||||
# Start server
|
||||
uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
|
||||
```
|
||||
|
||||
6. **Verify:**
|
||||
Open http://localhost:8080/docs in your browser.
|
||||
|
||||
### Option 2: Docker (Recommended for Production)
|
||||
|
||||
**Requirements:**
|
||||
- Docker
|
||||
- Docker Compose
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone https://github.com/yourusername/wled-screen-controller.git
|
||||
cd wled-screen-controller/server
|
||||
```
|
||||
|
||||
2. **Start with Docker Compose:**
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
3. **View logs:**
|
||||
```bash
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
4. **Verify:**
|
||||
Open http://localhost:8080/docs in your browser.
|
||||
|
||||
### Option 3: Docker (Manual Build)
|
||||
|
||||
```bash
|
||||
cd server
|
||||
docker build -t wled-screen-controller .
|
||||
|
||||
docker run -d \
|
||||
--name wled-controller \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
-v $(pwd)/logs:/app/logs \
|
||||
--network host \
|
||||
wled-screen-controller
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Home Assistant Integration
|
||||
|
||||
### Option 1: HACS (Recommended)
|
||||
|
||||
1. **Install HACS** if not already installed:
|
||||
- Follow instructions at https://hacs.xyz/docs/setup/download
|
||||
|
||||
2. **Add Custom Repository:**
|
||||
- Open HACS in Home Assistant
|
||||
- Click the three dots menu → Custom repositories
|
||||
- Add URL: `https://github.com/yourusername/wled-screen-controller`
|
||||
- Category: Integration
|
||||
- Click Add
|
||||
|
||||
3. **Install Integration:**
|
||||
- In HACS, search for "WLED Screen Controller"
|
||||
- Click Download
|
||||
- Restart Home Assistant
|
||||
|
||||
4. **Configure Integration:**
|
||||
- Go to Settings → Devices & Services
|
||||
- Click "+ Add Integration"
|
||||
- Search for "WLED Screen Controller"
|
||||
- Enter your server URL (e.g., `http://192.168.1.100:8080`)
|
||||
- Click Submit
|
||||
|
||||
### Option 2: Manual Installation
|
||||
|
||||
1. **Download Integration:**
|
||||
```bash
|
||||
cd /config # Your Home Assistant config directory
|
||||
mkdir -p custom_components
|
||||
```
|
||||
|
||||
2. **Copy Files:**
|
||||
Copy the `custom_components/wled_screen_controller` folder to your Home Assistant `custom_components` directory.
|
||||
|
||||
3. **Restart Home Assistant**
|
||||
|
||||
4. **Configure Integration:**
|
||||
- Go to Settings → Devices & Services
|
||||
- Click "+ Add Integration"
|
||||
- Search for "WLED Screen Controller"
|
||||
- Enter your server URL
|
||||
- Click Submit
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Start the Server
|
||||
|
||||
```bash
|
||||
cd wled-screen-controller/server
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 2. Attach Your WLED Device
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/devices \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Living Room TV",
|
||||
"url": "http://192.168.1.100",
|
||||
"led_count": 150
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Configure in Home Assistant
|
||||
|
||||
1. Add the integration (see above)
|
||||
2. Your WLED devices will appear automatically
|
||||
3. Use the switch to turn processing on/off
|
||||
4. Use the select to choose display
|
||||
5. Monitor FPS and status via sensors
|
||||
|
||||
### 4. Start Processing
|
||||
|
||||
Either via API:
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
|
||||
```
|
||||
|
||||
Or via Home Assistant:
|
||||
- Turn on the "{Device Name} Processing" switch
|
||||
|
||||
### 5. Enjoy Ambient Lighting!
|
||||
|
||||
Your WLED strip should now sync with your screen content!
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Won't Start
|
||||
|
||||
**Check Python version:**
|
||||
```bash
|
||||
python --version # Should be 3.11+
|
||||
```
|
||||
|
||||
**Check dependencies:**
|
||||
```bash
|
||||
pip list | grep fastapi
|
||||
```
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
# Docker
|
||||
docker-compose logs -f
|
||||
|
||||
# Python
|
||||
tail -f logs/wled_controller.log
|
||||
```
|
||||
|
||||
### Home Assistant Integration Not Appearing
|
||||
|
||||
1. Check HACS installation
|
||||
2. Clear browser cache
|
||||
3. Restart Home Assistant
|
||||
4. Check Home Assistant logs:
|
||||
- Settings → System → Logs
|
||||
- Search for "wled_screen_controller"
|
||||
|
||||
### Can't Connect to Server from Home Assistant
|
||||
|
||||
1. Verify server is running:
|
||||
```bash
|
||||
curl http://YOUR_SERVER_IP:8080/health
|
||||
```
|
||||
|
||||
2. Check firewall rules
|
||||
3. Ensure Home Assistant can reach server IP
|
||||
4. Try http:// not https://
|
||||
|
||||
### WLED Device Not Responding
|
||||
|
||||
1. Check WLED device is powered on
|
||||
2. Verify IP address is correct
|
||||
3. Test WLED directly:
|
||||
```bash
|
||||
curl http://YOUR_WLED_IP/json/info
|
||||
```
|
||||
|
||||
4. Check network connectivity
|
||||
|
||||
### Low FPS / Performance Issues
|
||||
|
||||
1. Reduce target FPS (Settings → Devices)
|
||||
2. Reduce `border_width` in settings
|
||||
3. Check CPU usage on server
|
||||
4. Consider reducing LED count
|
||||
|
||||
---
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Server Environment Variables
|
||||
|
||||
```bash
|
||||
# Docker .env file
|
||||
WLED_SERVER__HOST=0.0.0.0
|
||||
WLED_SERVER__PORT=8080
|
||||
WLED_SERVER__LOG_LEVEL=INFO
|
||||
WLED_PROCESSING__DEFAULT_FPS=30
|
||||
WLED_PROCESSING__BORDER_WIDTH=10
|
||||
```
|
||||
|
||||
### Home Assistant Automation Example
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "Auto Start WLED on TV On"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: media_player.living_room_tv
|
||||
to: "on"
|
||||
action:
|
||||
- service: switch.turn_on
|
||||
target:
|
||||
entity_id: switch.living_room_tv_processing
|
||||
|
||||
- alias: "Auto Stop WLED on TV Off"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: media_player.living_room_tv
|
||||
to: "off"
|
||||
action:
|
||||
- service: switch.turn_off
|
||||
target:
|
||||
entity_id: switch.living_room_tv_processing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [API Documentation](docs/API.md)
|
||||
- [Calibration Guide](docs/CALIBRATION.md)
|
||||
- [GitHub Issues](https://github.com/yourusername/wled-screen-controller/issues)
|
||||
Reference in New Issue
Block a user