Baldrick and xLights: Assign Ports, Upload and Test

A successful xLights setup makes three things agree: the model on your screen, the configuration in the controller and the cable plugged into the yard. Start with one strand or prop that already passes the controller's local test.

Reviewed October 29, 2026. These steps follow the current Baldrick and xLights documentation. Profile names and screen layout can vary with the installed xLights version. Select the profile for your actual Baldrick8 or Baldrick17; do not choose a similar controller solely because its port count matches.

1. Protect the working show folder

Save the current layout and controller settings, then make an xLights backup before changing an existing show. For a first bench setup, use a separate show folder with an obvious name such as Mattos Bench Test. That gives the experiment its own models and channels.

Keep a short record of the board's IP address, output lead, pixel protocol, count and color order. For the example below, the hardware is one matching 12V three-wire EVO strand with 100 RGB nodes on output 1. Change the example to the equipment actually connected.

2. Add one controller record

  1. Open the Controllers tab and use Discover to find the board on the reachable network.
  2. If discovery fails but its browser page opens, use Add Ethernet. Select ILightThat as the vendor and the matching Baldrick model/profile offered by your xLights installation.
  3. Enter the board's actual address. Give the record a useful location name, such as Porch Baldrick.
  4. For this new example, select DDP. Existing E1.31 or Art-Net shows can use their established plan; changing protocols is not required just to follow this guide.
  5. Enable Auto Layout Models, Auto Size and Full xLights Control where supported by the selected profile. Save the controller settings.
Manufacturer example of a Baldrick controller selected in xLights
Manufacturer example from Baldrick Boards manual. Firmware or software layout may differ; use your own device values.

Expected result: one controller row represents the physical board and opens the correct controller page. Two rows sharing the same address can place a controller into unmanaged mode and prevent the normal visualizer/upload workflow. Resolve an accidental duplicate in your backed-up layout before proceeding.

3. Define the physical strand or prop

In Layout, create or import the model. For the bench example, use a single-line model containing 100 RGB nodes. Select the named Baldrick as its controller and assign its connection to physical output 1. Set the pixel protocol to match the actual strand; for the three-wire EVO example, that is the WS2811-compatible setting.

A hundred RGB nodes use 300 color channels. This is a channel calculation, not a current measurement. An RGBW model uses a different channel count, and a four-wire dual-data product is not automatically RGBW. Keep the model type tied to the light's actual electronics.

Set supported controller brightness and color-order overrides deliberately. If you later push the model settings again, those overrides can replace a manual adjustment made in the controller. Choose one maintained configuration and record the result instead of compensating for the same error in several places.

4. Make the visualizer match the cables

Select the Baldrick on the Controllers tab and open Visualise. With automatic model layout enabled, assign the model to output 1. Its string count must match the physical wiring; a model unexpectedly occupying several ports usually needs its string definition checked.

For more than one model on an output, put them in the order the pixel data encounters them. A left window followed by a right window is a different connection from the reverse order, even when the total node count is identical.

Resolve the visualizer's reported errors, save, and use its print or CSV export option to keep a port map beside your setup notes. A clean visualizer is a software check; it still needs the physical chase test below.

5. Upload, then read the result back

Return to Controllers, select the correct board and choose Upload Output. Watch for a successful completion message. If your selected protocol/profile requires an input upload, follow the input-then-output workflow shown by xLights. A grayed-out Upload Input button is not itself a problem for a configuration that does not need that step.

Open the Baldrick page again and inspect the configured output. Check the model name, node count, ordering and brightness against your plan. Uploading output configuration sets up the controller; it does not store an entire musical xLights show inside a Baldrick8 or Baldrick17.

6. Send one controlled test from xLights

  1. Turn the Baldrick's own test mode off. Stop FPP or other software currently transmitting to this board.
  2. Open Tools → Test, select only the intended model or channels, and enable Output to Lights.
  3. Test red, green and blue at the planned initial brightness, then run a chase. Confirm all 100 example nodes respond and the chase starts at the physical input.
  4. Observe the controller's incoming-data status while testing. If local controller testing worked but this test fails, compare the destination address and channel setup before changing hardware.
  5. Stop the test and disable Output to Lights when finished.

Ready to expand: the first and last intended nodes respond, the colors agree, and each model occupies its planned physical location. Add the next model, repeat the upload and chase, then save a fresh backup.

7. Hand the verified layout to the show player

After layout or channel changes, re-render the affected sequences before transferring them. Use the same controller addresses and channel plan when moving playback to FPP. Our xLights-to-FPP checklist handles that handoff.

If the result changes between local test, xLights and FPP, use the Baldrick troubleshooting guide to isolate the stage that fails.

Sources and next steps

Explore the Mattos Baldrick Learning Center · All Mattos guides

Baldrick Guides · All Mattos learning resources