ledgrab/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}
  ]
}
```

## Automatic Calibration

The easiest way to calibrate your strip is the **Auto-Calibrate** wizard, available directly
from the calibration modal. No LED counting required — just answer three questions and tap four
corners.

### Prerequisites

- A **Color Strip Source** (not a device-only target) associated with the strip.
- A **WLED device** connected and reachable by LedGrab.

### How to Start

1. Open the **Calibration** modal for your strip source (pencil icon → Calibration tab).
2. Click the **Auto-calibrate** button in the modal footer.
3. Follow the five-step wizard.

### Wizard Steps

| Step | What you do |
| ---- | ----------- |
| 1. Device | Select the WLED device that drives the strip. |
| 2. Start corner | LED #0 lights up on your device. Tap the corner where you see it. |
| 3. Direction | Sweep a few LEDs light up in sequence. Tap the direction they move. |
| 4. Mark corners | Use the step buttons to sweep to each remaining corner, then tap **Mark corner**. Repeat for all 4 corners. |
| 5. Preview & Save | Review the detected layout (start position, direction, LED counts per edge). Click **Save** to apply. |

### What Happens in the Background

- A calibration session takes exclusive control of the device for the duration of the wizard;
  any previously running effect is paused and automatically restored when the wizard exits
  (whether by saving, cancelling, or closing the modal).
- The solved `CalibrationConfig` is written directly to the Color Strip Source via the existing
  PUT endpoint and takes effect immediately (no restart needed).

### Tips

- If LED #0 is hard to see, reduce ambient lighting briefly.
- The wizard works in the browser — desktop and Android TV app both supported.
- If you make a mistake in step 4, use **Step back** to re-mark the previous corner.

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