wled-screen-controller-mixed/docs/API.md

# 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,
  "brightness": 1.0,
  "smoothing": 0.3,
  "interpolation_mode": "average",
  "standby_interval": 1.0,
  "state_check_interval": 30
}
```

### PUT /api/v1/devices/{device_id}/settings

Update processing settings.

**Request:**
```json
{
  "display_index": 1,
  "fps": 60,
  "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