What is the difference between WLED 2D config and ledmap.json?

WLED 2D configuration handles standard rectangular matrices with serpentine wiring. ledmap.json is for irregular layouts — shapes with gaps, letter signs, or custom paths where a simple rectangle does not describe your panel.

Why does my animation look scrambled on a custom shape?

Without a correct ledmap.json, WLED assumes a linear strip or simple rectangle. Effects map to the wrong physical LEDs. A ledmap tells WLED which physical index belongs at each virtual grid position.

WLED ledmap.json Guide

Custom letter signs, irregular shapes, and non-standard wiring need a ledmap.json file. This guide explains why — and gives you a free visual generator.

Open Free Generator

When do you need ledmap.json?

Standard rectangle → use WLED 2D

16×16, 32×32, 32×8 panels with full grids — configure in WLED's 2D settings. See our setup guides.

Irregular shape → use ledmap.json

Channel letters, logos with holes, figure-8 layouts, partial grids, or freestyle wiring paths.

How the map works

A ledmap.json file contains a width, height, and a flat map array. Each entry is the physical LED index at that grid cell, or -1 for empty space. WLED remaps all 2D effects through this virtual grid.

{
  "n": "letter_C",
  "width": 9,
  "height": 5,
  "map": [
    -1, -1, 14, -1, 12, -1, 10, -1, -1,
    -1, 15, -1, 13, -1, 11, -1,  9, -1,
     0, -1, -1, -1, -1, -1, -1, -1,  8,
    ...
  ]
}

Example pattern from the WLED mapping documentation.

3-step workflow

Design — use our visual generator to match your wiring (serpentine, vertical, flips, or freestyle click-order).
Upload — open http://YOUR-DEVICE-IP/edit and upload ledmap.json to the device.
Play — use Pipplee to send animations, pixel art, and GIFs to the remapped grid.

Tip: In freestyle mode, start with an empty grid and click cells in the exact order your strip is wired. Numbers show the sequence.

Build your ledmap.json now

Free, runs in your browser — no account required.

Open Generator Tool