WLED runs on the microcontroller and sends data to the pixels. xLights runs on your computer and sends data to WLED. So it's important to have WLED installed and properly configured on all your controllers before setting up xLights.
I'm using three different controllers: one controlling my LED Top Hat, one controlling my LED Corset, and one running my Sparkle Motion Skirt. I've updated all three costume pieces to use Sparkle Motion boards, so they can talk to each other and sync up with WLED.
It is also possible to do this with one Sparkle Motion board that's running multiple light strands -- you don't need a separate board for each light strand. But for my costume pieces, it makes the most sense to have separate controllers, in case I'm not wearing them all together. This guide will show how to set up the controllers in either arrangement.
Install xLights
To get xLights installed, head over to the xLights Quick Start Guide. This will walk you through downloading and installing the software. Be sure to install the Vamp Plugins as well.
Once the software is installed, head to the Controllers tab to set up your Sparkle Motion boards.
Controller Setup
Be sure your Sparkle Motion board is set up with WLED and plugged in to power. It doesn't need to be plugged into your computer, just running on the same WiFi network.
Click "Add Ethernet" and set up your board as shown. I kept the same names in xLights as I have set in WLED. Set the IP Address to the static IP address you assigned to each controller in WLED (explained on the Additional Settings page of this guide). Choose WLED as the vendor and model, and Generic ESP32 as the variant.
Change the protocol to DDP. Click save.
Model Setup / LED Mapping
Click the Layout tab. This is where we tell xLights the physical shape, size, and location of each our light strands so it can map them correctly. There are a lot of premade models available at the top of the right hand window. Click through them to see which most closely matches your pixel layout.
For my top hat, I have one pixel strand wrapped in a spiral with 13 rows and about 36 pixels on each row. For the skirt, I have a long strand of pebble pixels that are attached in a serpentine strand, with 20 columns of 15 lights. The corset is trickier - each strand has a different number of lights and some of the strands have a higher pixel density than others. I was able to map all three in xLights. It took some trial and error, but the mapping tools are powerful.
Select the model you want and then draw a box in the black field with your mouse to place your project. This black field is like your movie screen. You can set up a picture of your house or your stage and place your various light strands on it so they match "real life".
You'll be able to run an animation that spans all your pieces, so getting them placed correctly in relation to each other will enable the magic to happen.
The top hat and skirt both use the "matrix" model, even though they are constructed differently. Here are screenshots of the settings for these two models.
"Strings" refers to the number of physical LED strips connected to the controller: each of these projects just connect to one GPIO pin, so the correct entry for "Strings" is 1.
"Nodes" refers to the total number of pixels in your strip.
"Strands" refers to how many times it spirals or zig-zags back and forth.
"Port" refers to the GPIO pin your light strand is connected to. Generally port 1 is the first pin set aside for LED connection. On the Sparkle Motion Mini, pin 32 is port 1 and pin 33 is port 2.
For the corset, I used a custom model. Since my LED strips all have different numbers of pixels, and some have different densities, the matrix model wouldn't work as well.
Click the three dots next to "Model Data" to open the custom editor. Create a grid that's larger than your pixel grid by a few lines. My corset had a max of 50 pixels in one strand so I made my grid 65 pixels high, to give myself some working room.
Click the "output to lights" checkbox and then start typing numbers in the boxes to match the placement of your lights, starting with pixel 1. Each light will illuminate when you highlight its box, making it much easier to keep everything straight.
The "active" and "auto increment" check boxes will automatically add numbers to boxes you click in. This is very handy when you're following a strip. With these two tools you can click-click-click in boxes and the numbers will auto-increment. You'll know when to switch to the next row because each pixel illuminates as you enter it.
Because my strips have different densities, I had to add in some blank spaces to some of the strips in order to get everything to line up right. What worked best for me was starting with the highest-density and longest strip (one of my strips has 50 pixels) and then working out from there.
Finally, create a group with all your models. This will allow you to run a single animation on all three boards, treating them as one very complicated display. You'll still have the ability to run separate animations and turn each piece on or off independently.
There are a lot of resources available online to help you with model selection and mapping. We will do some testing in the next few steps and you can always come back and change it later on, so if you don't get it perfect on the first try, don't worry.
Head back to the Controllers tab and select "Visualize". If you've assigned ports to your models in the Layout tab, these should already be assigned. Here is where you can change this around if needed: if you have multiple LED strips on one controller, this is where you tell xLights which strip goes on which port.
Close the port window and click "Save". Then click the "Upload Output" button to send the configuration to the controller.
Page last edited September 04, 2025
Text editor powered by tinymce.
