What is ledmap.json in WLED?

ledmap.json tells WLED how to map a virtual 2D grid onto your physical LED strip order. Each cell in the map array holds the physical LED index for that grid position, or -1 for gaps. This is essential for irregular shapes like letters, logos, or matrices with missing pixels.

Where do I upload ledmap.json on WLED?

Open http://YOUR-DEVICE-IP/edit in a browser (not in AP mode), then upload ledmap.json to the root of the device filesystem. WLED loads it automatically on reboot.

When do I need a custom LED map instead of WLED 2D settings?

Use ledmap.json when your panel is not a perfect rectangle — letter signs, figures with gaps, multiple disconnected regions, or unusual wiring paths. For standard 16x16 or 32x8 rectangles, WLED's built-in 2D configuration is usually enough.

WLED ledmap.json Generator

Build custom LED maps for irregular matrices — letter signs, shapes with gaps, or non-standard wiring. Click the grid, download ledmap.json, upload to WLED, then play content with Pipplee.

Array

W × H

Start empty (all off)

Mode

Normal Freestyle

Normal: auto-number by wiring options.
Freestyle: click cells in wire order (start empty).

Wiring

Serpentine Vertical V-flip (start bottom) H-flip (start right) Discard gaps (−1)

Export

Matrix name

Grid editor

Click cells to toggle the LED chip on/off. Active cells show the WS2812 icon; gaps show −1.

JSON preview

Wiring algorithm inspired by community tools including Intrinsically-Sublime's generator. Official WLED docs: Mapping guide.

What is ledmap.json?

Standard WLED 2D configuration works for rectangular panels. But many builds are not perfect rectangles — channel letters, figure-8 shapes, logos with holes, or panels with unused pixel positions. That's where ledmap.json comes in.

The file defines a virtual grid (width × height) and a map array. Each grid cell holds the physical LED index wired to that position, or -1 for a gap. WLED uses this to remap effects and apps like Pipplee onto your actual hardware layout. See the official WLED mapping documentation.

How to upload to WLED

Generate and download ledmap.json using the tool above.
Connect to the same network as your WLED device.
Open http://YOUR-DEVICE-IP/edit in a browser (does not work in AP mode).
Upload ledmap.json to the device root filesystem.
Reboot WLED — the map loads automatically. You can disable WLED's standard 2D panel config when using a ledmap.

Then play content with Pipplee

Once your map is uploaded, Pipplee sends animations, pixel art, GIFs, and scrolling text to the remapped grid — automatically sized to your virtual width and height.

Get Pipplee Pixel Art Converter All Guides

Video walkthrough coming soon

We're preparing a step-by-step example — letter-sign layout from grid to live LEDs.