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

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

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