How do I map LED numbers for a serpentine strip without doing it by hand?

Nov 05, 2026 Last reply: 2 hours ago 4 Replies

First reply

Jake_Arrow

You can skip the spreadsheet entirely. FastLED's XYMatrix example already does what you're after: you define the matrix width and height in the code, and an XY() function turns x,y coordinates into a strip index. There's a built-in branch in that function for a serpentine…

Read the full reply

I'm building a window display for Halloween using a rope light bent into a vertical zigzag pattern inside a wooden frame. It looks great lit up, but I'm stuck on figuring out the pixel numbering for the matrix code. Every column has a different starting number depending on whether the strip is going up or down that row, and I keep losing track halfway through. Right now I'm just lighting up one column at a time, writing down wich numbers glow, then plugging those into a spreadsheet. It works but it's slow and I've allready made at least two mistakes that caused weird artifacts in my effects. Is there a smarter way to do this? I saw something about an online mapping tool that generates the arrays for you, but I'm not sure how it handles a serpentine layout where the direction flips at each bend. Also, does anyone know if I can just define the matrix in code with width and height and let the library figure out the ordering, or do I still need the full list of pixel positions? I'd rather spend my time on the animations than counting LEDs. Any tips appreciated.


You can skip the spreadsheet entirely. FastLED's XYMatrix example already does what you're after: you define the matrix width and height in the code, and an XY() function turns x,y coordinates into a strip index. There's a built-in branch in that function for a serpentine layout, where it checks whether the row is even or odd and flips the counting direction accordingly. If your rope runs as vertical columns instead of horizontal rows, just swap the width and height numbers so width becomes the number of columns and height becomes the number of LEDs per column. The flip then happens at each bend going across, which matches your zigzag exactly.

The only things you actually have to know are: does the rope start at the top or bottom, and is it a true serpentine (continuous) or does it fold back on itself in some spots? If a bend in the frame creates a gap or a doubled-up section where the counting doesn't just reverse cleanly, that's the one case where you'd need to override the math for a column or two. Otherwise the library handles all of it and you never touch a pixel list. I've also used the online mapper for irregular layouts, and it does fine with serpentine arrangements as long as you give it the coordinates. But for a regular grid like yours it's honestly overkill, since the code approach needs no external tools at all. One tip that saved me a lot of headaches: once you've got the XY function set up, run a checkerboard pattern first. Light every other pixel in a checker pattern. If you see solid lines instead of a checkerboard, or a stripe that jumps a column, you'll know immediately whether your flip logic is off by one or starting on the wrong end. It's much faster to debug that way than chasing weird artifacts in a running animation.

And if some effects still look scrambled after all that, it's usually because the effect itself is written for a different width and height, not because your mapping is wrong.

Been there with a serpentine setup on my garage door frame last year. The thing that finally saved my sanity was a dry erase marker on the wooden frame itself, writing the pixel number right next to each bend. Then I just eyeballed the XY function against the physical numbers and caught a flipped column in about a minute. For testing, I'd add to the checkerboard idea and run the pattern slow, one row at a time, so the direction of each column is obvious. Also worth checking wether your rope starts at the top left or bottom left before you write any code, that got me twice.

One thing I'd add is to label your data direction at the very first LED before you commit to any mapping, because the strip has an arrow or a printed input marker near the connector and if you accidentally feed it from the wrong end the whole numbering is mirrored and no amount of fiddling with the flip logic will fix it. I learned that the hard way on a porch column build and spent an evening convinced my coordinates were wrong when really I was just wired backwards. Also worth deciding early whether your origin is top-left or bottom-left and sticking to it, since half the example code assumes one and half assumes the other, and mixing them is what ussually makes effects come out upside down even when the mapping itself checks out.

Another trick that worked for me on a grid build: temporarily run a single color wash where each column is a slightly diferent shade of the same color, red fading toward orange or whatever. You can literally see where one column ends and the next begins, and if a column shows two shades you know the flip is wrong right there. Took me ten minutes and zero spreadsheet work.

Join the Discussion

Have something to add? Share your thoughts — no account required.

Didn't find your answer?

Ask the community — no account required