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.

Parts

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. 

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.

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 or Opera “desktop” browsers. Other browsers (Safari, Firefox, Explorer and anything mobile) won’t work.

Setup & Preferences

Use It

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:

1. 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.
2. 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).
3. Try re-uploading the WLED software. 
4. 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.
5. If your lights came on in blue or green instead of yellow, your color order is wrong. See below to fix.
6. If only half your lights came on, be sure you've got the correct number in the "length" field under LED preferences.
7. 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.
8. 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.

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.

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.

Server Description (Name)

Find this on the User Interface screen.

Brightness Limiter

Find this on the LED Settings screen.

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.

WLED App

Backup Config & Presets

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:

• Monster Matrix
• LED Festival Coat
• Sound Reactive Top Hat
• Sparkle Skirt 2D

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! 

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.

Custom Model

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.

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. 

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. 

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. 

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.

• xLights Quick Start Guide
• xLights Beginner Tutorial (YouTube)
• xLights Sequences Sharing/For Sale

There are dozens of tutorials available on YouTube and even online courses available for learning this massively deep program. Go wild.

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