Your first xLights win can be one prop showing the right colors in the right order. Get that working, save it, and use the same process as you add to the yard.
We would start with something you can keep beside you while learning. Our EVO Stake Set, for example, lists ten stakes with five pixels each: 50 RGB pixels total. A single verified coro prop or short pixel strand works as a learning project too. Pick one and keep the first setup manageable.
Write down the hardware before opening xLights
Record your controller model and network address, the physical output port, pixel protocol, voltage, connector, and actual node count. Check the controller and pixel instructions together. Matching connector shells do not verify voltage or wiring.
Power down before changing connections. Use the controller and power supply in their required assembled configuration. You want an accessible test setup, with mains wiring protected, before anything gets mounted on the house.
The official xLights quick-start guide is a useful reference as software labels change. If you are still choosing the hardware, use our Start Here guide.
1. Give this display its own show folder
Choose a clearly named folder for the layout, controller configuration, and sequences. Keep your related media organized. Check which show folder xLights has open before editing; an older folder can make a working setup look as though it disappeared.
Save a separate backup before major changes, including the sequences and media you need to run the show. See the official show-folder guide and backup instructions.
2. Make the model describe the real prop
In Layout, add the appropriate shape or import the exact vendor model. Give it a name you will recognize on a cable label, such as Front Window Left. Check its node count and starting location.
For the 50-pixel stake example, a simple 50-node model can be enough for the first output test. For a coro prop, verify the product size, model revision, and wiring path before pushing pixels.
The preview position describes where the prop sits in the yard. Wiring and controller settings describe where its data goes. Moving a model across the preview does not change the physical controller port. The xLights model guide explains those layout tools.
3. Add your actual controller
For an Ethernet controller, create the Ethernet entry and select its vendor, model, and variant where available. Enter the address of your device and choose a protocol supported by both the controller and the player you intend to use.
Open the controller's configuration page to confirm you are reaching the right box. Do not copy a tutorial's example IP address into your yard without checking your network. Use the same controller name in xLights, on the enclosure, and on your notes. The controller quick start covers the fields.
4. Put the prop on the port that feeds it
For a supported controller with automatic model layout enabled, use Controller Visualizer to assign the model to the correct port. If several props share one data chain, put them in the order their cables follow. Resolve reported configuration errors before uploading.
Use the input and output upload actions supported by that controller and protocol. Read overwrite prompts carefully if a working configuration already exists. After uploading, check the controller page for the expected port and pixel count. See Controller Visualizer and the testing instructions.
5. Check colors, then chase direction
Stop other players and test patterns. In Tools > Test, select the intended model or channels and enable Output to Lights. Use a modest intensity within your electrical design. Test solid red, green, and blue, then run a chase.
| What happens | Check this next |
|---|---|
| Nothing responds | Output enabled, device address, selected channels, active port, power, and data connection. |
| A different prop lights | Physical cable labels, port assignment, and channel mapping. |
| Red consistently appears green | Channel alignment and color order. Check whether the model or controller already applies a correction; change one setting at a time. |
| The chase visits the wrong parts | Starting node, wiring path, and exact model version. |
These are starting points for diagnosis, not proof that a component failed. The official Test reference covers individual-node and model selection.
6. Make one short sequence
Create an animation sequence, include the model, and add a simple effect. Save, render, and compare the preview with the lights. Then try a musical sequence with audio you are authorized to use. Follow the New Sequence guide for the sequence types.
Label the cable and save the working settings before adding another prop. If you need us, send Support@Mattosdesigns.com the prop, controller, software version, port, node count, and a short video. “All 50 pixels respond, but red turns green” gives us a much clearer next step than “nothing works right.”
Keep learning
- How to Import an xLights Model and Match Your Prop Wiring
- xLights Controllers, Ports, Channels, and Universes Explained
- Move Your xLights Show to Falcon Player: A Setup Checklist
Browse all Mattos education and support guides.
Reviewed October 29, 2026.
