WLED 2D Matrix Setup: Panels, Serpentine Wiring, Several Panels and Gaps
Set up an LED matrix in WLED: find the wiring, fill in 2D Configuration for one or more panels, test with Scrolling Text, fix mirrored effects, map gaps.
Written by Jamie Conde, who builds WLED Max at MeowScript. WLED Max is an independent app and is not affiliated with or endorsed by the official WLED project.
Quick answer: in Config›2D Configuration, set Strip or panel to 2D Matrix, enter the panel size (for a 16x16 panel, 16 x 16) and click Populate. Then, under Panel 0, set where the 1st LED is (Top or Bottom, Left or Right), whether the rows run Horizontal or Vertical, and tick Serpentine if every second row runs backwards. Save, pick the Scrolling Text effect, and if the text is mirrored or upside down, change the 1st LED corner until it reads correctly.
The step people miss: Populate only creates the panels and their positions. How the LEDs run inside each panel is set per panel, below it.
Before you start
- LED count. In LED & Hardware (LED Preferences on 0.14 and 0.15), the length must be the total number of LEDs: 256 for one 16x16 panel, 512 for two.
- Board. Any ESP32 handles matrices well. An ESP8266 can drive a 16x16 panel, but the 2D effects are heavier than strip effects, and bigger matrices run out of memory. The tiny ESP02 “min” build has no 2D at all.
- Power. A 16x16 panel at full white can draw several amps. Set Maximum PSU Current before trying bright effects (what the setting does).
Find how your matrix is wired
Every matrix is one long strip folded into rows or columns. WLED needs three facts:
- Where LED 0 is: which corner the data comes in.
- Rows or columns: does the strip run across (Horizontal) or up and down (Vertical) first?
- Serpentine or not: does every second row run back the other way (zigzag), or does each row start on the same side (progressive)?
Most flexible 8x32 and 16x16 panels sold for WLED are serpentine. To check, set the matrix to 1D for a moment (Strip or panel 1D Strip), make a segment from 0 to 20, and look at which LEDs light up. You can see the first row and where the second one starts.
Serpentine, horizontal, 1st LED top left Progressive, horizontal, 1st LED top left
0 1 2 3 0 1 2 3
7 6 5 4 4 5 6 7
8 9 10 11 8 9 10 11
15 14 13 12 12 13 14 15
One panel
- Config›2D Configuration, Strip or panel: 2D Matrix.
- Open Matrix Generator. Panel dimensions (WxH): the size in LEDs, for example 32 x 8. Horizontal panels 1, Vertical panels 1. Click Populate.
- Under Panel set-up, Panel 0 now has your size. Set its 1st LED (for example Top, Left), its Orientation (Horizontal for rows) and Serpentine.
- Check the drawing on the page: the line shows the order the LEDs are wired in. It should match what you saw on the panel.
- Click Save. If 2D effects don’t show up in the effect list after saving, open the page and save once more, or restart the light.
Several panels
For a bigger display made of identical panels, the generator places them for you.
- In Matrix Generator, Panel dimensions is the size of one panel (16 x 16), and Horizontal panels and Vertical panels are how many you have across and down (2 and 1 for a 32x16 display).
- The generator’s own 1st panel, Orientation and Serpentine describe how the panels are chained: which panel the data enters first, and whether the chain goes across or down and zigzags. They don’t describe the LEDs inside a panel.
- Click Populate. You get Panel 0, Panel 1 and so on, each with an Offset X and Offset Y (counted in LEDs from the top left corner).
- Now set 1st LED, Orientation and Serpentine on every panel. The generator leaves those at their defaults, and this is where most multi-panel layouts go wrong. Panels that are mounted upside down get the opposite corner.
- Check the drawing, save, test.
Panels don’t have to be identical or in a neat grid. Set the number of panels by hand and give each one its own size and offset; WLED takes the outer edges of all panels as the size of the matrix. Up to 18 panels are allowed (64 on 0.14), and neither side of the whole matrix can be more than 255 LEDs.
Test it with Scrolling Text
Pick the Scrolling Text effect (ID 122) on a segment that covers the whole matrix. With an empty segment name it shows the date and time, which is enough to judge the layout.
| What you see | What’s wrong | Fix |
|---|---|---|
| Text is readable and scrolls across | Nothing | Done |
| Text is mirrored | Left and right swapped | Change the 1st LED Left/Right |
| Text is upside down | Top and bottom swapped | Change the 1st LED Top/Bottom |
| Every second row is mirrored, text looks torn | Serpentine is wrong | Tick or untick Serpentine |
| Text runs down the matrix, or looks diagonal and scrambled | Rows and columns swapped | Change Orientation |
| One panel looks wrong, the rest are fine | That panel’s settings or offset | Fix that panel only |
Give the segment a name and Scrolling Text shows that instead, which is a nice touch for a window (“MERRY CHRISTMAS”) or a scoreboard. On WLED 16 the name can mix text and time, like NOW #HHMM; on 0.14 and 0.15 the name has to start with the token.
Segments and effects on a matrix
On a matrix, a segment is a rectangle: start and stop on X, and start and stop on Y. The Reverse and Mirror options come in an X and a Y version, plus Transpose, which swaps rows and columns. One matrix can carry several segments, for example a scrolling name across the top rows and an effect below.
The effect list now has two kinds of effects:
- 2D effects, drawn for the matrix: Matrix (digital rain), Game Of Life, DNA, Drift, Octopus, Rotozoomer and many more. On WLED 16 with an ESP32 there are also particle effects like PS Fireworks.
- 1D effects, made for strips. The segment’s Expand 1D FX setting decides how they cover the matrix: Pixels runs the strip through the matrix row by row, Bar runs the effect up each column (every column the same, except effects like Drip that treat each column separately), Arc and Corner draw it outward from a corner as rings or squares. 0.15 and 16 add Pinwheel.
More on what the sliders do and how to preview effects is in the effects list.
Gaps: when not every grid spot has an LED
Some displays aren’t a full rectangle: a cutout for a window handle, icicle drops of different lengths, a sign with missing letters. WLED handles this with a gap file: a list with one value per grid spot, row by row from the top left.
1: an LED is here.-1: no LED here; WLED skips this spot when counting LEDs along the wire.0: an LED is here but stays dark (it counts, but never lights).
Save the list as 2d-gaps.json, upload it under Gap file on the 2D Configuration page, and save. For a 4x3 matrix with the bottom right spot missing:
[1,1,1,1,
1,1,1,1,
1,1,1,-1]
The LED count in LED & Hardware is then the number of real LEDs (11 here), not the grid size. A full worked example with hanging drops is in the icicle lights guide.
For full control over every LED’s position, WLED also reads a ledmap.json file. On 0.15 and newer a 2D ledmap can also carry width and height keys next to the map, which set the matrix size.
Matrix ideas for the holidays
- Mega tree: strands hanging from the top are columns. Set Orientation to Vertical, the width to the number of strands and the height to the LEDs per strand; Serpentine if the strands go down and back up. The cone squeezes pictures toward the top, which most effects get away with. More in the Christmas tree guide.
- Window curtain: a curtain of LED strands is the same setup, and Scrolling Text turns it into a greeting.
- Countdown: on New Year’s Eve, WLED can show the time left to midnight as text on a matrix (countdown guide).
- Shows to music: when a matrix becomes one part of a bigger show, xLights maps it from the computer, and WLED’s own 2D setup should then stay off (WLED and xLights).
Common problems
- No 2D effects in the list: the matrix isn’t saved as 2D, or the segment doesn’t cover the matrix. Save 2D Configuration again and reset the segment to the full size.
- Only part of the matrix lights: the LED count in LED & Hardware is smaller than the matrix.
- The matrix falls back to a strip after saving: the panels add up to more than WLED allows (a side longer than 255, or more LEDs than the board’s limit). WLED then quietly goes back to 1D.
- Effects stutter on a big matrix: too many LEDs for the board or the frame rate. Use an ESP32, split the matrix over two outputs, or lower the effect’s resolution with grouping.
- Flicker or random colors on one panel: a data or power problem, not a setting. Check the connection between panels and feed power to each panel.
FAQ
How do I set up a matrix in WLED? Config, 2D Configuration, Strip or panel 2D Matrix, enter the panel size, Populate, then set 1st LED, Orientation and Serpentine for each panel and save.
Why is my WLED matrix mirrored? The 1st LED corner is on the wrong side. Change Left to Right (mirrored text) or Top to Bottom (upside down text) for that panel.
What does Serpentine mean in WLED? The strip zigzags: every second row (or column) runs back in the opposite direction. Most flexible panels are wired this way.
Can WLED run several matrix panels as one display? Yes, up to 18 panels (64 on 0.14) with their own size, wiring and position, as long as neither side of the whole display exceeds 255 LEDs.