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

# 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!