Overview
It’s time to put on a show.
If you’ve tried the new Sparkle Motion boards with WLED, you’ve already seen how easy it is to dive into the world of addressable LEDs. With just a few clicks, you can transform your project into a glowing, animated masterpiece. But maybe you’re ready for more — ready to take your lights beyond instant animations and into full-blown performances.
That’s where xLights comes in.
Think of WLED as a smart remote control: it installs on an Adafruit Sparkle Motion board in minutes, and from your phone or computer, you can change colors, trigger patterns, and get dazzling results right away. It’s simple, satisfying, and perfect when you want instant gratification.
xLights, on the other hand, is more like a movie editor for lights. It runs on your computer and lets you choreograph intricate shows that sync with music, follow a schedule, or span thousands of LEDs in massive holiday or festival displays. It has a steeper learning curve, but gives you far more creative power.
This tutorial walks through setting up both WLED and xLights with three Sparkle Motion boards, then guides you through sequencing your very first light show.
The Sparkle Motion ESP32 line of boards are designed to work seamlessly with WLED and xLights. The costume pieces used as demos in this tutorial are all using Sparkle Motion Mini boards, since they're small and light and easy to hide. For larger projects, the original Sparkle Motion is a great choice, with more GPIO pins available and 12v support. The Sparkle Motion Stick is a great choice for mobile projects, since you can plug it right into a USB battery.
Page last edited September 04, 2025
Text editor powered by tinymce.
Wiring Diagram
Connect your lights to the Sparkle Motion board as shown:
- DI (data IN) to GPIO of your choice: Note the number and remember this number for the Config step
- +5v to 5v
- G to G
You can power most projects through the USB port on the Sparkle Motion boards. The board will support up to a 4A draw, which is different from a lot of microcontrollers: if you did this with the QT Py Pico it could fry your board. The Sparkle Motion is designed for this kind of project, so can power a lot of LEDs.
However: if you have a LOT of lights -- more than 800 or so -- it's still good practice to power the lights as shown in the third graphic, so you're not pulling all that power through the board.
Page last edited September 04, 2025
Text editor powered by tinymce.
WLED Installation
This page will guide you through how to install WLED on the Sparkle Motion boards.
Driver Update
Some versions of our controllers have a new serial chip which needs a driver installed before we can install WLED. Head over to our How to Install Drivers for WCH USB to Serial Chips tutorial, and download and install the new driver.
Install WLED
These next steps require a Web Serial-compatible browser. As of this writing, that means Google Chrome, Microsoft Edge, Firefox 151 or Opera “desktop” browsers. Other browsers (Safari, older versions of Firefox, Explorer and anything mobile) won’t work.
Visit https://install.wled.me/
Plug your microcontroller into your computer with a known good USB cable. Click "Install" and select the port for your board.
Depending on the USB-to-serial bridge chip on the board, you might see one or two serial ports. On Mac, for instance, there might be both “/dev/cu.usbmodem[number]” and “/dev/cu.wchusbserial[number]”. Use the “wchusbserial” one.
After successful installation, enter your WiFi network name and password when prompted. This must be a 2.4 GHz WiFi network; ESP32 does not support 5 GHz networks. If it can’t connect, then as a fallback WLED will create its own 2.4 GHz WiFi access point.
If you don't see the "Connect to Wi-Fi" prompt, you'll need to set up your WiFi network using AP (access point) mode. Open up your WiFi settings and look for a WiFi network called WLED-AP. Connect to this network using the default password wled1234. The WLED interface will pop up in its own browser.
From here, go into Config/Wifi Settings and enter your WiFi credentials near the top. Give your project a name in the mDNS field a little further down the page. Now you can type in "projectname.local" (where "projectname" is your mDNS name) into any web browser on the same wifi network to access your microcontroller.
You can also scan the QR code below to open access point mode.
For more help and troubleshooting tips visit the Getting Started page on the WLED knowledge base.
WiFi Setup
Head to the WiFi Setup screen under Config and create a good URL so you can control your project from any web-enabled device. Call it something you'll remember, that's easy to type into any web browser on your WiFi network in order to connect to your project.
In Safari or Chrome on your phone or computer, type in this web address to access the WLED interface: http://projectname.local (where "projectname" is whatever you put into this field).
Check out the Additional Settings page for more info on accessing your project. WLED has an "access point mode" that doesn't require a WiFi network for when you're out on the go. It's also helpful to download one of the WLED apps to help manage and organize your projects.
LED Setup
Next, head to the LED Preferences tab under the Config menu.
Scroll down to Hardware Setup. Put your total number of LEDs into the Length field, and change GPIO to the number associated with the LED data pin on your Sparkle Motion. Make sure to select the correct Color Order for your LEDs as well.
The Sparkle Motion Mini uses pins 32 or 33, the Sparkle Motion Stick uses pins 21 and 22, and the Sparkle Motion (original) uses 19, 21, and 22. The numbers are printed right on the boards so enter the number of the pin you connected to.
Now you can use any computer or handheld device to control your LEDs.
Make sure your device is on the same WiFi network as your board. Navigate to your custom URL (projectname.local/ ) in a web browser. You'll see a color picker above a whole bunch of color palette choices.
Choose a color, choose an effect, and watch your lights animate and glow!
Save your favorite combinations as presets, create playlists, control the speed and intensity of the animations, and lots more. This web app is incredibly intuitive and easy to use.
Head over to the WLED wiki at https://kno.wled.ge/ to delve into all the particulars.
Troubleshooting
If your lights didn't come on, here are a few things to try:
- Head back to WLED and check your pinout configuration under LED Preferences. Be sure the pin number is the correct GPIO for the attachment point you used.
- Check your wiring! Be sure you connected to the IN end of the LED strip. These strips can be inconsistent so this is a pretty common problem. Use an alligator clip to try connecting the data wire on the other end (the power and ground wires should work from either end).
- Try re-uploading the WLED software.
- If the lights come on but you can't control them: i.e. you type in "projectname.local" into your browser and it won't connect, make sure you're on the correct WiFi network. If you're on a different network than the one you set up the sofware on, you won't see the WLED connection.
- If your lights came on in blue or green instead of yellow, your color order is wrong. See below to fix.
- If only half your lights came on, be sure you've got the correct number in the "length" field under LED preferences.
- If your lights came on in a variety of weird colors and looking like a 1950s diner interior, you may have the wrong LED strip type selected. RGBW strips and RGB strips are not the same, so be sure you've got the correct strip type or you'll get very odd behavior.
- If your microcontroller hangs or keeps rebooting, or gets really hot, you may have the power and ground lines switched. Unplug right away and check: this is a fast way to brick your controller.
Page last edited September 04, 2025
Text editor powered by tinymce.
WLED Additional Settings
Static IP Address
With multiple instances of WLED running, and the additional xLights layer, it's a really good idea to assign a static IP address to each of your controllers. That way if your router loses power or your projects get disconnected, they'll reconnect with the same address. If you use DHCP / dynamic addresses (the default in WLED), you may lose connectivity with your projects when the addresses change.
Under Config > WiFi setup, find the Static IP address fields. Enter the IP address you'd like to assign to your controller on the first line, and the static gateway IP address on the second line.
For most home routers, the gateway will be 192.168.1.1 and the IP should start with 192.168, then you can use either a 1 or a 0, and the final number should be unique to your microcontroller.
Note down the IP addresses you used as you'll need them when we set up xLights.
If you're not sure which IP addresses are available on your home network, you can download the Net Analyzer app from your favorite app store and connect it to your WiFi to see which addresses are used and which are free.
When dealing with a lot of instances of WLED, it's a great idea to give each instance a separate name in the Server Description field. This name will show up in browser tabs and also in the WLED Native app, which is recommended when you've got a lot of projects to keep track of.
WLED automatically limits the brightness of your project so your power supply doesn't get over-taxed. The default amperage is 850mA, which is a little low for most power supplies.
For some projects, especially battery-powered projects, having the limiter turned on is a good idea. But if you're not getting the brightness you expect, try adjusting this number to match the amperage of your power supply or battery pack.
Access Point (AP) Mode
While you're home, it's easy to control your project over your local WiFi network. But when you're out at a festival, you probably don't have WiFi access. It's still possible to connect to your project and control it using WLED's Access Point Mode.
Turn your project on and give it a minute or two to start broadcasting. Look in your WiFi networks and find WLED-AP - this is a mini WiFi network being broadcast by the microcontroller. Connect to it - the default password is "wled123". An instance of WLED will automatically pop up and you can control your project from anywhere.
If you're putting your lights up in public, it's a good idea to change the AP Mode default password so strangers can't log in and control your lights. This could be a security risk.
AP Mode only broadcasts for a few minutes after you boot up the board, so if you don't see the WLED-AP network try rebooting.
There are a couple different apps available to manage your WLED projects. Name and organize your projects, and find them quickly without having to type in a URL. Check the Apple or Android store for downloads.
My favorite is "WLED Native". It allows you to organize multiple instances and easily switch between devices without having to remember any URLs.
Under Config / Security & Updates, you will find a place to back up your data. It's a good idea to back up your config file as soon as you're happy with the settings. Save it as a .json file on your computer. Now you can prototype and experiment to your heart's content, and if everything breaks, just re-upload this file. Or, if you're doing another build, you can use this feature to copy all your settings from one board to another.
Page last edited September 04, 2025
Text editor powered by tinymce.
WLED 2d Matrix
If you're planning to set up xLights on a board once you're done installing WLED: STOP. The 2d setup can make xLights setup go haywire. Set up your xLights matrix models first, then come back and set up the 2d matrix in WLED.
If you're using a 2d matrix such as an LED curtain or net, WLED has a handy 2d matrix setup feature that will take care of the mapping for you. Head to Config and choose the 2D Configuration tab.
Check out these tutorials for more about 2d mapping with WLED:
Change the dropdown to read 2d Matrix, and additional options will appear. If you want to sync more than one panel, you can do it here.
Set up your layout numbers to match the number of rows and columns in your project. These nets have 20 pixels in a row and 20 pixels per meter.
You can also change orientation here - my pixels start in the lower left corner and finish in the upper right.
Matrix Effects
WLED has a hefty number of matrix effects that appear in the list when you've got your 2d matrix set up. Many of them can be customized with speed and intensity sliders, or different color palettes. Go wild!
Page last edited September 04, 2025
Text editor powered by tinymce.
xLights Setup and Mapping
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.
Create a Test Sequence
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.
Musical Sequence
The real impact of xLights can be found in its music sequencing tools.
Now that we've done our setup and our mapping, it's time to play! Create a new sequence and choose "musical sequence". Keep it 20fps for better rendering. Choose a song that moves you: I prefer songs with visual imagery in the lyrics to make it easy to come up with animations for the different parts of the song.
I started out using "Girl on Fire" by Alicia Keys. xLights has a "Fire" animation that can be made music reactive (click the "grow with music" checkbox) so it was a lot of fun to make my different costume pieces "burn" in time to the song.
There is so much that can be done using just the fire effect. Things I found that were very effective:
- Stagger the start and end times over the three pieces so they come on one after the next
- Switch between running the animation individually and running it on the group
- Turn it upside down! Or make it burn left to right
- Change the hue slider to have the fire change colors
- Have all the pieces go dark and then come on with the beat / hook
- Don't change animations too fast - give your audience time to take it in
Page last edited September 04, 2025
Text editor powered by tinymce.
