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
|
||||
Reference in New Issue
Block a user