Add hundreds of lights to your home or yard with these fantastic Pebble Pixel Nets. Adafruit carries them in a variety of sizes, from 1x1m to 1x6m large, and they are chainable and expandable so no vision is too big.

These nets use 12v power, which can be easily handled by the Adafruit Sparkle Motion microcontroller. It has 4 powered LED outputs, a power manager so you can run 12v or 5v lights, and an onboard I2S microphone, which makes sound-reactive projects a snap. 

The build is fairly easy, with no soldering required (though adding connectors can make your life easier). This gives you time to focus on making beautiful sequences and enjoying your pretty lights.

WLED and xLights

Both WLED and xLights are open source control software for LEDs. The Sparkle Motion board works great with both. What's the difference?

WLED is a fast and easy way to get your lights doing beautiful things. It's easy to install and configure, and you can be up and running within just a few minutes. WLED's software lives on the microcontroller and works over your local WiFi network to talk to each controller. It's easy to sync your projects together and use the preset animations and customize them to a certain extent.  I use WLED when I want to "set it and forget it" -- the controller boots up when I power it on and then the animations just run automatically.

xLights is a more advanced option, and it's biggest strength is sequencing. This program is used by industry professionals and also by homeowners who want a crazy mad holiday display in their front yard, with animated trees, windows, roof lines, arches, and matrices. xLights makes it possible to run animations across all your different lights at once. It's free to download and use, and there are online communities where people share and sell their favorite sequences. xLights really shines when it's showtime: sequence all your different lights to a piece of music and impress the heck out of your neighbors.

To run xLights you first need to install and configure WLED, so work through that section first.

Parts

These nets require 12v power. For just 1-2m of net, this 5a power supply is just fine. If you're using the bigger nets or chaining multiple nets together, or if you're doing an outdoor installation, look for a beefier power supply.

This net will also run on battery power. Our 8 x AA battery holder supplies 12v and will run a 1-2m net for several hours. It's insufficient for larger projects, but sometimes a few hours is all you need.

Connectors & Wire

Using connectors allow you to remove your Sparkle Motion controller from your project, which is especially helpful when it's a larger scale project that's hard to move. Adding 3-pin JST connectors is a bit more work during setup but can save you a lot of time down the road. They're pretty weatherproof and hold up to wind and rain. I like these color-coded ones.

• 3 Pin Color-coded JST Connectors

Get some heat-shrink tubing too!

For a Large Install

Bigger (800+ pixel) installations will require thicker wire connections and more power. Here are a couple suggestions to get you started.

• 16g Power Wire
• 12v 25A power supply

Standard JST connectors won't work in this case: the wires inside those little connectors just aren't rated to carry that much current. Solder your wires together or use a 12v rated connector like these. 

• 18AWG 12v Pigtail Barrel Connectors

These nets are 20 pixels wide with 5mm spacing. A 1m net is a 20x20 square and contains 400 pixels.

The Sparkle Motion board has 4 outputs: 3 in the screw terminal and another using the pins just to the left of it. WLED prefers no more than 800 pixels per output (though it will work with more, just not as smoothly) and xLights sets a hard limit of 1000 pixels per output. 

Keep this in mind when you're setting up your project. For the larger nets with 1200-1800 pixels, you may want to add a second data line that connects into the net after the first 800 pixels, for best performance. 

It's also a good idea to connect another power line at the far end of the net -- the manufacturers have broken out power injection wires every 800 pixels on the bigger nets to make this easy. If you're getting flickering or voltage drop across the pixels, try adding another power injection point.

The Sparkle Motion is built to power LEDs, but for very large projects with larger power draws, it's a good idea to run the power directly to the lights instead of pulling it all through the board.

How many LEDs Can I Connect?

The Sparkle Motion board has four outputs for LED strips: 3 in the screw terminal and one more using the GPIO pins next to the screw terminal. It has a "Classic" ESP32 chip onboard.

Driving Pixels with WLED

From the WLED Knowledge base:

For perfect performance, it is recommended to use 512 LEDs/pin with 4 outputs for a total of 2048 LEDs.
For very good performance, it is recommended to use 800 LEDs/pin with 4 outputs for a total of 3200 LEDs.
For good performance, you can use 1000 LEDs/pin with 4 outputs for a total of 4000 LEDs.
For okay performance, you can use 1000 LEDs/pin with 5 outputs for a total of 5000 LEDs.
For okay performance, you can use 800 LEDs/pin with 6 outputs for a total of 4800 LEDs.
ESP32 can calculate about 65k-85k LEDs per second (that means 1000 LEDs @~70fps, 2000 LEDs @~35fps, 4000 LEDs @~18fps)
4 outputs seem to be the sweet spot.

How Do I Power It?

For Adafruit's 1x1 meter net, these power supplies will work great.

• 12v 5a Power Supply
• Adjustable 5-24v Power Supply

For larger projects (more than 800 pixels), or projects that will be placed outdoors, try this power supply (or similar):

• LED Driver 300 Watt 25A 12v Indoor/Outdoor Power Supply

For wearable or portable projects, you can use this 8xAA battery pack for 12v pixels. But if you're making a wearable project, you might also want to check out the Sparkle Motion Mini board. It's not quite as powerful and won't drive 12v pixels, but can power up to 4A at 5v and that's plenty for most costume pieces. Check out our 5v Pebble Pixels to go along with it.

LED strips often come with these connectors already attached, but there seems to be no standard for whether the factories attach the male or the female connector on the "in" end. For my own peace of mind, I try to be consistent and always use the male side of the connectors on the microcontrollers, and the female on the "in" end of my LED strip. Data is flowing "out" from the microcontroller and "in" to the strip, so the male/female metaphor makes good sense in this arrangement. 

There is also no standard as to which way the color coding is wired on these connectors. Some have a red wire on the left side, some on the right side. Some have no color coding at all.

Hooking your strips up "backwards" (accidentally connecting a red wire to a black wire) can damage your board and your LEDs, so it's important to be really careful when you're setting up your connectors.

Be as consistent as possible with color coding and throw away any connectors you've got in the drawer that are wired "backwards" from the rest. 

Connect the net to the controller and plug the controller in with at 12v power supply. These boards come pre-loaded with a rainbow animation on pin 19, so if your lights come on, you've got it right and you're good to go.

Troubleshooting

No lights? Here are a few things to try:

• Check your wire connections. These screw terminals can be tricky to manage and they break pretty easily. Try using a different set of holes if you think your connections might be the problem.
• Get WLED installed and running on your microcontroller
• Be sure you're connecting to the "input" end of the net and not the "output" end. These nets are directional and will only work if you connect to "in".
• If your lights are on but are super dim or flickering, you may have a powering issue. Try power injection or try using a screw terminal to power the lights directly instead of through the board. 

For larger projects with more than 800 pixels or so, the wiring gets a little bit more complicated. It's not a good idea to pull too much power through the Sparkle Motion board, and bigger LED installations can draw a fair amount of power. 

You'll also want to start a new data line every 800 pixels or so, if you're planning to run WLED or xLights on your Sparkle Motion Board. 

Data Outputs

If you're running WLED or X-lights, these controllers work best at around 800-1000 pixels per output. Adafruit 4 meter nets have 1600 lights. So for these nets, for best performance, it's a good idea to run a data line to the middle of the net and connect it up right after pixel 800. 

It's possible to use the 3rd and 4th input on the board to control more nets and lights. With xLights or WLED you can also sync multiple controllers together, so expansion is pretty easy. 

This section will show how to install and set up WLED on your Sparkle Motion board, and set up a 2 dimensional matrix so you can run mapped, 2D animations on your net.

The Sparkle Motion board has a lot more features we're not covering in this guide. It has an onboard I2S microphone, for instant audio-reactive projects. It has an IR sensor so anyone can control your project with a simple infrared remote. There are a lot of settings and features that can really make your project shine.

Check out the Sparkle Motion Guide for information on how to use these features and more.

If you're planning to set up xLights on this board once you're done installing WLED: STOP. The 2-d setup can make xLights setup go haywire. Set up your xLights matrix models first, then come back and set up the 2-d matrix in WLED. 

If you're using a 2-d 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! 

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 board.

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. Mine is called Butterfly1 in WLED so I kept the same name in xLights. Choose WLED as the vendor and model, and Generic ESP32 as the variant. Change the protocol to DDP. Click save.

Model Setup

Next head to the Layout tab. Click the Matrix tool and draw a box in the black area - don't worry about the size or shape yet, just get it onto the field.

Click one of the dots on the matrix to select it. In the lower left, set up the parameters as shown. Give it a name, and click the "Don't Zig Zag" box since our matrix is not serpentine.

• Under # Strings, enter 1. This means there's one data line feeding all the LEDs. 
• Nodes/String: total number of pixels on this data line. Enter 400 for a 1 meter net or 800 for a 2 meter net. 
• Strands/String: Total number of rows in your net. 20 for a 1m net or 40 for a 2m net.
• Starting Location: Change this so it matches your net's orientation

If you have a 4 meter net, or two smaller nets you'd like to "merge" into one, add a second matrix and set it up the same way. For my setup. I'm using one 4m net and I have attached a second data line at the 801st pixel.  Drag it into place under the first matrix to line it up.

If you have multiple models, you can create a Group. I've grouped my two net sections into one group called Net1. When I run animations on the Group, the whole net will act as one continuous matrix instead of two separate pieces.

Save your models once you're happy with the layout.

Connect Ports

Create a Sequence

Let's create a test sequence and see if we can get our lights responding. In the "Sequence" tab in xLights, go to File > New Sequence. 

Select the "Butterfly Effect" animation and drag it to your timeline, on the line that has your matrix model or group. Drag the handle out so the effect takes up a good chunk of the timeline, and press "play". You should see the animation appear on the onscreen model in the lower left of the screen.

To send your sequence to the LED net, click the light bulb button in the top center of the screen.

Troubleshooting

If your net doesn'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.
• 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 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.