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:
341
docs/API.md
Normal file
341
docs/API.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# WLED Screen Controller API Documentation
|
||||
|
||||
Complete REST API reference for the WLED Screen Controller server.
|
||||
|
||||
**Base URL:** `http://localhost:8080`
|
||||
**API Version:** v1
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Health & Info](#health--info)
|
||||
- [Device Management](#device-management)
|
||||
- [Processing Control](#processing-control)
|
||||
- [Settings Management](#settings-management)
|
||||
- [Calibration](#calibration)
|
||||
- [Metrics](#metrics)
|
||||
|
||||
---
|
||||
|
||||
## Health & Info
|
||||
|
||||
### GET /health
|
||||
|
||||
Health check endpoint.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2026-02-06T12:00:00Z",
|
||||
"version": "0.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/version
|
||||
|
||||
Get version information.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"version": "0.1.0",
|
||||
"python_version": "3.11.0",
|
||||
"api_version": "v1"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/config/displays
|
||||
|
||||
List available displays for screen capture.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"displays": [
|
||||
{
|
||||
"index": 0,
|
||||
"name": "Display 1",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"is_primary": true
|
||||
}
|
||||
],
|
||||
"count": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Device Management
|
||||
|
||||
### POST /api/v1/devices
|
||||
|
||||
Create and attach a new WLED device.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "Living Room TV",
|
||||
"url": "http://192.168.1.100",
|
||||
"led_count": 150
|
||||
}
|
||||
```
|
||||
|
||||
**Response:** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": "device_abc123",
|
||||
"name": "Living Room TV",
|
||||
"url": "http://192.168.1.100",
|
||||
"led_count": 150,
|
||||
"enabled": true,
|
||||
"status": "disconnected",
|
||||
"settings": {
|
||||
"display_index": 0,
|
||||
"fps": 30,
|
||||
"border_width": 10
|
||||
},
|
||||
"calibration": {
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [...]
|
||||
},
|
||||
"created_at": "2026-02-06T12:00:00Z",
|
||||
"updated_at": "2026-02-06T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/devices
|
||||
|
||||
List all attached devices.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"devices": [...],
|
||||
"count": 2
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/devices/{device_id}
|
||||
|
||||
Get device details.
|
||||
|
||||
**Response:** Same as POST response
|
||||
|
||||
### PUT /api/v1/devices/{device_id}
|
||||
|
||||
Update device information.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /api/v1/devices/{device_id}
|
||||
|
||||
Delete/detach a device.
|
||||
|
||||
**Response:** `204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## Processing Control
|
||||
|
||||
### POST /api/v1/devices/{device_id}/start
|
||||
|
||||
Start screen processing for a device.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "started",
|
||||
"device_id": "device_abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/devices/{device_id}/stop
|
||||
|
||||
Stop screen processing.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "stopped",
|
||||
"device_id": "device_abc123"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/devices/{device_id}/state
|
||||
|
||||
Get current processing state.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"device_id": "device_abc123",
|
||||
"processing": true,
|
||||
"fps_actual": 29.8,
|
||||
"fps_target": 30,
|
||||
"display_index": 0,
|
||||
"last_update": "2026-02-06T12:00:00Z",
|
||||
"errors": []
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Settings Management
|
||||
|
||||
### GET /api/v1/devices/{device_id}/settings
|
||||
|
||||
Get processing settings.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"display_index": 0,
|
||||
"fps": 30,
|
||||
"border_width": 10,
|
||||
"color_correction": {
|
||||
"gamma": 2.2,
|
||||
"saturation": 1.0,
|
||||
"brightness": 1.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PUT /api/v1/devices/{device_id}/settings
|
||||
|
||||
Update processing settings.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"display_index": 1,
|
||||
"fps": 60,
|
||||
"border_width": 15,
|
||||
"color_correction": {
|
||||
"gamma": 2.4,
|
||||
"saturation": 1.2,
|
||||
"brightness": 0.8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Calibration
|
||||
|
||||
### GET /api/v1/devices/{device_id}/calibration
|
||||
|
||||
Get calibration configuration.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [
|
||||
{
|
||||
"edge": "bottom",
|
||||
"led_start": 0,
|
||||
"led_count": 40,
|
||||
"reverse": false
|
||||
},
|
||||
{
|
||||
"edge": "right",
|
||||
"led_start": 40,
|
||||
"led_count": 30,
|
||||
"reverse": false
|
||||
},
|
||||
{
|
||||
"edge": "top",
|
||||
"led_start": 70,
|
||||
"led_count": 40,
|
||||
"reverse": true
|
||||
},
|
||||
{
|
||||
"edge": "left",
|
||||
"led_start": 110,
|
||||
"led_count": 40,
|
||||
"reverse": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### PUT /api/v1/devices/{device_id}/calibration
|
||||
|
||||
Update calibration.
|
||||
|
||||
**Request:** Same as GET response
|
||||
|
||||
### POST /api/v1/devices/{device_id}/calibration/test
|
||||
|
||||
Test calibration by lighting up specific edge.
|
||||
|
||||
**Query Parameters:**
|
||||
- `edge`: Edge to test (top, right, bottom, left)
|
||||
- `color`: RGB color array (e.g., [255, 0, 0])
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
### GET /api/v1/devices/{device_id}/metrics
|
||||
|
||||
Get detailed processing metrics.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"device_id": "device_abc123",
|
||||
"processing": true,
|
||||
"fps_actual": 29.8,
|
||||
"fps_target": 30,
|
||||
"uptime_seconds": 3600.5,
|
||||
"frames_processed": 107415,
|
||||
"errors_count": 2,
|
||||
"last_error": null,
|
||||
"last_update": "2026-02-06T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints may return error responses in this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "ErrorType",
|
||||
"message": "Human-readable error message",
|
||||
"detail": {...},
|
||||
"timestamp": "2026-02-06T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Common HTTP Status Codes:**
|
||||
- `200 OK` - Success
|
||||
- `201 Created` - Resource created
|
||||
- `204 No Content` - Success with no response body
|
||||
- `400 Bad Request` - Invalid request
|
||||
- `404 Not Found` - Resource not found
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
---
|
||||
|
||||
## Interactive Documentation
|
||||
|
||||
The server provides interactive API documentation:
|
||||
|
||||
- **Swagger UI:** http://localhost:8080/docs
|
||||
- **ReDoc:** http://localhost:8080/redoc
|
||||
- **OpenAPI JSON:** http://localhost:8080/openapi.json
|
||||
277
docs/CALIBRATION.md
Normal file
277
docs/CALIBRATION.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# Calibration Guide
|
||||
|
||||
This guide explains how to calibrate your WLED strip to match your screen layout.
|
||||
|
||||
## Overview
|
||||
|
||||
Calibration maps screen border pixels to LED positions on your WLED strip. Proper calibration ensures that the colors on your LEDs accurately reflect what's on your screen edges.
|
||||
|
||||
## Understanding LED Layout
|
||||
|
||||
### Physical Setup
|
||||
|
||||
Most WLED ambient lighting setups have LEDs arranged around a TV/monitor:
|
||||
|
||||
```
|
||||
TOP (40 LEDs)
|
||||
┌─────────────────┐
|
||||
│ │
|
||||
LEFT│ │RIGHT
|
||||
(40)│ │(30)
|
||||
│ │
|
||||
└─────────────────┘
|
||||
BOTTOM (40 LEDs)
|
||||
```
|
||||
|
||||
### LED Numbering
|
||||
|
||||
WLED strips are numbered sequentially. You need to know:
|
||||
|
||||
1. **Starting Position:** Where is LED #0?
|
||||
2. **Direction:** Clockwise or counterclockwise?
|
||||
3. **LEDs per Edge:** How many LEDs on each side?
|
||||
|
||||
## Default Calibration
|
||||
|
||||
When you attach a device, a default calibration is created:
|
||||
|
||||
- **Layout:** Clockwise
|
||||
- **Start Position:** Bottom-left corner
|
||||
- **LED Distribution:** Evenly distributed across 4 edges
|
||||
|
||||
### Example (150 LEDs):
|
||||
|
||||
```json
|
||||
{
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [
|
||||
{"edge": "bottom", "led_start": 0, "led_count": 38},
|
||||
{"edge": "right", "led_start": 38, "led_count": 37},
|
||||
{"edge": "top", "led_start": 75, "led_count": 38, "reverse": true},
|
||||
{"edge": "left", "led_start": 113, "led_count": 37, "reverse": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Calibration
|
||||
|
||||
### Step 1: Identify Your LED Layout
|
||||
|
||||
1. Turn on your WLED device
|
||||
2. Note which LED is #0 (first LED)
|
||||
3. Observe the direction LEDs are numbered
|
||||
4. Count LEDs on each edge
|
||||
|
||||
### Step 2: Create Calibration Config
|
||||
|
||||
Create a calibration configuration matching your setup:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [
|
||||
{
|
||||
"edge": "bottom",
|
||||
"led_start": 0,
|
||||
"led_count": 50,
|
||||
"reverse": false
|
||||
},
|
||||
{
|
||||
"edge": "right",
|
||||
"led_start": 50,
|
||||
"led_count": 30,
|
||||
"reverse": false
|
||||
},
|
||||
{
|
||||
"edge": "top",
|
||||
"led_start": 80,
|
||||
"led_count": 50,
|
||||
"reverse": true
|
||||
},
|
||||
{
|
||||
"edge": "left",
|
||||
"led_start": 130,
|
||||
"led_count": 30,
|
||||
"reverse": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Apply Calibration
|
||||
|
||||
Update via API:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:8080/api/v1/devices/{device_id}/calibration \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @calibration.json
|
||||
```
|
||||
|
||||
### Step 4: Test Calibration
|
||||
|
||||
Test each edge to verify:
|
||||
|
||||
```bash
|
||||
# Test top edge (should light up top LEDs)
|
||||
curl -X POST "http://localhost:8080/api/v1/devices/{device_id}/calibration/test?edge=top&color=[255,0,0]"
|
||||
|
||||
# Test right edge
|
||||
curl -X POST "http://localhost:8080/api/v1/devices/{device_id}/calibration/test?edge=right&color=[0,255,0]"
|
||||
|
||||
# Test bottom edge
|
||||
curl -X POST "http://localhost:8080/api/v1/devices/{device_id}/calibration/test?edge=bottom&color=[0,0,255]"
|
||||
|
||||
# Test left edge
|
||||
curl -X POST "http://localhost:8080/api/v1/devices/{device_id}/calibration/test?edge=left&color=[255,255,0]"
|
||||
```
|
||||
|
||||
## Calibration Parameters
|
||||
|
||||
### Layout
|
||||
|
||||
- `clockwise`: LEDs numbered in clockwise direction
|
||||
- `counterclockwise`: LEDs numbered counter-clockwise
|
||||
|
||||
### Start Position
|
||||
|
||||
Where LED #0 is located:
|
||||
|
||||
- `top_left`
|
||||
- `top_right`
|
||||
- `bottom_left` (most common)
|
||||
- `bottom_right`
|
||||
|
||||
### Segments
|
||||
|
||||
Each segment defines one edge of the screen:
|
||||
|
||||
- `edge`: Which screen edge (`top`, `right`, `bottom`, `left`)
|
||||
- `led_start`: First LED index for this edge
|
||||
- `led_count`: Number of LEDs on this edge
|
||||
- `reverse`: Whether to reverse LED order for this edge
|
||||
|
||||
### Reverse Flag
|
||||
|
||||
The `reverse` flag is used when LEDs go the opposite direction from screen pixels:
|
||||
|
||||
- **Top edge:** Usually reversed (LEDs go right-to-left)
|
||||
- **Bottom edge:** Usually not reversed (LEDs go left-to-right)
|
||||
- **Left edge:** Usually reversed (LEDs go bottom-to-top)
|
||||
- **Right edge:** Usually not reversed (LEDs go top-to-bottom)
|
||||
|
||||
## Common Layouts
|
||||
|
||||
### Standard Clockwise (Bottom-Left Start)
|
||||
|
||||
```json
|
||||
{
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [
|
||||
{"edge": "bottom", "led_start": 0, "led_count": 40, "reverse": false},
|
||||
{"edge": "right", "led_start": 40, "led_count": 30, "reverse": false},
|
||||
{"edge": "top", "led_start": 70, "led_count": 40, "reverse": true},
|
||||
{"edge": "left", "led_start": 110, "led_count": 40, "reverse": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Counter-Clockwise (Top-Left Start)
|
||||
|
||||
```json
|
||||
{
|
||||
"layout": "counterclockwise",
|
||||
"start_position": "top_left",
|
||||
"segments": [
|
||||
{"edge": "top", "led_start": 0, "led_count": 50, "reverse": false},
|
||||
{"edge": "left", "led_start": 50, "led_count": 30, "reverse": false},
|
||||
{"edge": "bottom", "led_start": 80, "led_count": 50, "reverse": true},
|
||||
{"edge": "right", "led_start": 130, "led_count": 30, "reverse": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Three-Sided Setup (No Top Edge)
|
||||
|
||||
```json
|
||||
{
|
||||
"layout": "clockwise",
|
||||
"start_position": "bottom_left",
|
||||
"segments": [
|
||||
{"edge": "bottom", "led_start": 0, "led_count": 50, "reverse": false},
|
||||
{"edge": "right", "led_start": 50, "led_count": 40, "reverse": false},
|
||||
{"edge": "left", "led_start": 90, "led_count": 40, "reverse": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Colors Don't Match
|
||||
|
||||
**Problem:** LED colors don't match screen content.
|
||||
|
||||
**Solutions:**
|
||||
1. Verify LED start indices don't overlap
|
||||
2. Check reverse flags for each edge
|
||||
3. Test each edge individually
|
||||
4. Verify total LED count matches device
|
||||
|
||||
### LEDs Light Up Wrong Edge
|
||||
|
||||
**Problem:** Top edge lights up when bottom should.
|
||||
|
||||
**Solutions:**
|
||||
1. Check `led_start` values for each segment
|
||||
2. Verify `layout` (clockwise vs counterclockwise)
|
||||
3. Confirm `start_position` matches your physical setup
|
||||
|
||||
### Corner LEDs Wrong
|
||||
|
||||
**Problem:** Corner LEDs show wrong colors.
|
||||
|
||||
**Solutions:**
|
||||
1. Adjust LED counts per edge
|
||||
2. Ensure segments don't overlap
|
||||
3. Check if corner LEDs should be in adjacent segment
|
||||
|
||||
### Some LEDs Don't Light Up
|
||||
|
||||
**Problem:** Part of the strip stays dark.
|
||||
|
||||
**Solutions:**
|
||||
1. Verify total LEDs in calibration matches device
|
||||
2. Check for gaps in LED indices
|
||||
3. Ensure all edges are defined if LEDs exist there
|
||||
|
||||
## Validation
|
||||
|
||||
The calibration system automatically validates:
|
||||
|
||||
- No duplicate edges
|
||||
- No overlapping LED indices
|
||||
- All LED counts are positive
|
||||
- All start indices are non-negative
|
||||
|
||||
If validation fails, you'll receive an error message explaining the issue.
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Start Simple:** Use default calibration first, then customize
|
||||
2. **Test Often:** Use test endpoint after each change
|
||||
3. **Document Your Setup:** Save your working calibration
|
||||
4. **Physical Labels:** Label your LED strip to remember layout
|
||||
5. **Photos Help:** Take photos of your setup with LED numbers visible
|
||||
|
||||
## Example Workflow
|
||||
|
||||
1. Install WLED strip around TV
|
||||
2. Note LED #0 position
|
||||
3. Create device in API (gets default calibration)
|
||||
4. Test default calibration
|
||||
5. Adjust based on test results
|
||||
6. Save final calibration
|
||||
7. Start processing and enjoy!
|
||||
Reference in New Issue
Block a user