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):

{
  "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:

{
  "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:

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:

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

{
  "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)

{
  "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)

{
  "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!