Let's create a test sequence and see if we can get our lights responding, and upload some good test patterns to test our mapping.
In the "Sequence" tab in xLights, go to File > New Sequence.
For now, just to keep things simple, choose Animation and 20 FPS (frames per second). This will create a sequence that's populated with your models and ready to test your lights. Click "quick start".
You'll see a workspace with a timeline on the right with your models listed out, a visualizer window on the left, and a bunch of animation buttons across the top.
The fourth button from the left is the "bars" animation. This is a wonderful one to use to test your mapping setup: if the bars line up and move in the right direction, you've done it right. If not, this animation will show you what to fix.
Drag the "bars" animation to your timeline and drop it into the black space. Drag out the handles on the edges until it's about 30 seconds long.
Select 2-3 colors from the color picker (near the top center of the screen). Press "play" and see what happens to the visualizer.
Click the "light bulb" icon at the top of the screen to send the data to your LEDs. If you've got everything set up correctly, your lights should come on and (more or less) match the visualizer.
If your lights are going up instead of down, or moving vertically instead of horizontally, head back to the Layout tab and change a few settings in the model. Then come back and see if it looks right.
Next, change the Direction dropdown from "up" to "left". This will orient the bars vertically and move them across your matrix in the other direction.
Running these patterns will point out any settings you have incorrect. Head back to the Layout tab and try changing the model settings until this test pattern matches the visualizer as much as possible.
On my top hat, this was the best I could do with this test. The hat is a bit concave and I wasn't careful about wrapping the LEDs in a perfect cylinder, so the center strips have fewer lights than the top and bottom. It "stretches" the pattern but not in an unpleasant way. I could go back and create a custom model, and if I wanted to show video or intricate images (definitely an option with xLights!) then I might do so. But for now I'm happy enough.
Groups
Once you have all your individual models mapped and aligned as best you can, it's time to play with grouping. You'll see in the timeline that the group you made in the last section is listed in its own line on your timeline.
Cut-and-paste your "bars" animation into this row and click your light bulb. The "bars" animation will span all three of your pieces and create a virtual map on everything at once. MAGIC!
Play around with this for a bit and see how "tight" you can get your various projects.
These tests certainly didn't work correctly the first time for me, and I had to spend quite a bit of time hunting down issues and tweaking models to get things to look right.
It's important to get your models set up and working BEFORE you dive deep into sequencing. I found that changing my models too much would sometimes crash my sequence and I'd have to start again from the beginning -- so spend some time testing and tweaking each of your models before you put in all the artistic work! So spend some time and get this right.
Troubleshooting
If your lights don't respond, here are a few things to try:
- Check your settings in WLED. Be sure the board is working and showing animations on the net before setting up your controller in xLights.
- If you've set up a 2D matrix in WLED, try setting it back to 1D strip before configuring xLights. Having two different matrix definitions can confuse things. I might even recommend reinstalling WLED to be sure all that old data is cleared out.
- Be sure you've saved your controller settings and clicked "Upload Output"
- If your matrix is trying to join 20 ports on the controller, change the "string" number to 1
- Be sure your computer and the controller are on the same WiFi network
- Did you click the light bulb icon? That's what turns the show on and off / starts and stops sending data to the lights.
- If you see a stripey effect on your lights, try turning on/off "Don't Zig Zag" on your model.
- If it's just not working, try deleting all your models and controllers and start again.
More Resources
xLights is a pro-level program with lots of functions and settings. It can be a little overwhelming at first, but the possibilities are grand. Here are a few links with tutorials and inspiration to get you started.
There are dozens of tutorials available on YouTube and even online courses available for learning this massively deep program. Go wild.
Page last edited September 04, 2025
Text editor powered by tinymce.
