Running an LED matrix with WLED and LedFx

October 2026 · minotor.org

A Minotor rig was a laptop sending frames over USB to an Arduino running LEDuino, which clocked them into WS2801 pixels. The maintained setup closest to it puts an ESP32 running WLED where the Arduino was, and LedFx on the laptop. LedFx listens to the music, draws a 2D effect at the matrix's resolution and streams it to the ESP32 over Wi-Fi or Ethernet. This guide walks through it for the Minotor team's own wall, 24 × 16 WS2801 pixels in six 8 × 8 panels (team setup).

The settings are for WLED v16.0.1 (7 July 2026) and LedFx v2.2.1 (4 October 2026), taken from both projects' documentation and source code. We have not wired a wall this way ourselves, so test each step before moving on to the next.

What you need

Part	Why
An ESP32 board (the classic ESP32)	WLED's quick start recommends an ESP32 for new projects; ESP8266 support is ending. The classic chip also takes every microphone type if you later want sound on the board itself.
A SN74AHCT125 level shifter, or a WLED controller board with one built in	The ESP32 outputs 3.3 V signals. WLED's list of compatible controllers calls a level shifter mandatory, especially with 12 V pixels. The WS2801 needs two lines shifted, clock and data.
5 V for the ESP32 and the shifter	The ATX supplies from the build guide already have it on the red wire.
The existing 12 V supplies	Unchanged. One panel draws about 5 A at full white, so the wall needs three ATX supplies.
A computer for LedFx	Windows (a portable build), macOS or Linux (installed with pip, Python 3.11 to 3.14), or a Raspberry Pi.

Wiring

The wires that went to the Arduino Mega's SPI pins now go to the shifter's outputs: green data, which was on pin 51, and yellow clock, which was on pin 52. Use GPIO 23 for data and GPIO 18 for clock. WLED's source names these as the ESP32's VSPI pins, and they are inside the range its quick start recommends for LED outputs.

From	Through the SN74AHCT125	To
ESP32 GPIO 23	input 1A, output 1Y	pixel data in (green)
ESP32 GPIO 18	input 2A, output 2Y	pixel clock in (yellow)
5 V (ATX red)	VCC	also the ESP32 board's 5 V pin
Ground (ATX black)	GND, all four OE pins, unused inputs 3A and 4A	ESP32 GND and pixel ground (blue)

Leave outputs 3Y and 4Y unconnected, as in WLED's wiring guide. Every ground has to meet: supplies, ESP32 and pixels.

The panels are already chained, so drive the whole wall from one output. On an ESP32, WLED gives hardware SPI only to the first clock-and-data output and drives any further ones in software. A comment in its source warns that the WS2801 latches after a 500 µs pause and "is prone to flickering if bit-banged too slow."

Flash WLED and join the network

Open install.wled.me in desktop Chrome, Edge, Opera or Firefox 151 or newer (Safari cannot talk to the board), plug the ESP32 in over USB and install the current release.
Join the Wi-Fi network WLED-AP with the password wled1234 and open the page it offers.
Under Config, WiFi Setup, enter your own network. The E1.31 page warns that streaming to a board reached through WLED-AP may not work, so put the ESP32 and the laptop on the same network. Ticking "Disable WiFi sleep" on the same page can reduce stutter, at the cost of a little more power.

The quick start says the first 30 LEDs light orange after flashing. That check assumes a WS2812 strip on the default pin, so a WS2801 wall stays dark until the next step.

For a stage, a classic ESP32 board with an Ethernet port avoids the Wi-Fi link altogether. Flash the Ethernet build (the installer offers it) and pick the board under Ethernet type at the bottom of WiFi Setup. Ethernet takes GPIOs 19, 21, 22, 25, 26 and 27, and some adapters also take 23, so choose data and clock pins the board leaves free. WLED's download notes say this build has "some restrictions for 2-wire LEDs" when used on Wi-Fi only.

LED Preferences

Under Config, LED Preferences, set the first output and save.

Setting	Value	Note
Type	WS2801 RGB	Shows the Data and Clock GPIO fields.
Length	384	24 × 16. WLED's source allows up to 16,384 on a classic ESP32.
Data GPIO / Clock GPIO	23 / 18	As wired.
Clock	Normal (5 MHz)	The default. If the far panels glitch on long cables, try Slow (2 MHz).
Color order	by test	The team's pixels needed BRG in FastLED. Pick a solid red in WLED and change this until the wall shows red.
mA/LED	Custom, 80	0.96 W at 12 V is 80 mA per pixel at full white.
Maximum PSU Current	what your supplies can carry	Full white is 384 × 80 mA = 30,720 mA. At the build guide's 10 A per supply on 12 V, three supplies give 30,000 mA.

The limiter counts milliamps per pixel whatever the voltage, so enter the 12 V currents.

Describe the matrix in 2D Configuration

The team's wiki shows the pixels in each panel running in a serpentine, back and forth along the rows, and says the panels are chained "using the same logic." It does not say which corner the chain starts from, so treat the values below as a first guess and correct them with a test pattern.

Config, 2D Configuration: set "Strip or panel" to 2D Matrix.
Open Matrix Generator. Panel dimensions 8 x 8, Horizontal panels 3, Vertical panels 2, 1st panel Top and Left, Orientation Horizontal, Serpentine ticked. Press Populate.
The generator only places the six panels on the grid. Its own note says the values "will not affect final layout" and that you may need to update each panel afterwards. Under LED panel layout, give every panel its 1st LED corner, Orientation Horizontal and Serpentine ticked, then save.
Pick a 2D effect with an obvious direction, such as Scrolling Text, and look at the wall. Every other row reversed inside a panel points to that panel's Serpentine box. Whole panels in the wrong place point to the generator's 1st panel and Serpentine settings. Mirrored or upside-down text usually means a wrong 1st LED corner.

Get this right in WLED before adding LedFx. LedFx sends each frame as one flat run of pixels, row after row, and relies on WLED's map to put each pixel in the right place.

Connect LedFx

Install and start LedFx: on Windows the portable download, started with LedFx.exe --open-ui; on macOS brew install portaudio and then python3 -m pip install ledfx; on Linux python -m pip install ledfx.
Choose what it listens to under Settings, Audio. To use the computer's own playback instead of a microphone, LedFx's docs route it through BlackHole on macOS, Stereo Mix on Windows and PulseAudio on Linux.
Add the ESP32 as a WLED device, by its IP address, or let LedFx scan the network for WLED devices. LedFx reads the pixel count from WLED and, when WLED reports a matrix, sets the virtual's Rows to the matrix height, 16 here. If the device settings show Rows as 1, set it to 16.
Pick an effect from the Matrix group: Equalizer2d, Flame, Plasma2d, Digital Rain, Noise, Waterfall, Game of Life or Texter. Flip Horizontal, Flip Vertical and Rotate in the effect settings fix an image that comes out turned, but they should not be needed if the WLED test above read correctly.

In WLED's Sync Interfaces page, keep "Respect LED Maps" ticked. It is on by default in v16, and WLED's source applies the 2D map to streamed pixels only while it is on. With it off, LedFx's frame lands in wiring order and every other row of each panel runs backwards. The Timeout field on the same page (2,500 ms by default) is how long WLED waits after the stream stops before going back to its own effect.

DDP, E1.31 or Art-Net

LedFx streams to a WLED device with DDP unless you change its sync mode, and its docs recommend DDP for WLED 0.13 and later. WLED always listens for DDP on port 4048. The other two protocols matter when the sender is something else, such as a lighting desk, xLights or Resolume Arena, which sends Art-Net.

Protocol	Port in WLED	The 384-pixel wall	Set in WLED
DDP	4048	No universes; LedFx's default for WLED	Nothing
E1.31 (sACN)	5568	3 universes: 170 + 170 + 44 pixels	Sync Interfaces: type E1.31, start universe, DMX mode Multi RGB, then reboot
Art-Net	6454	3 universes, the same split	As E1.31, with the type set to Art-Net, then reboot

WLED fits 170 RGB pixels, 510 channels, into a universe and recommends no more than three universes for a steady 40 frames per second, which this wall just fits. If you add WLED to LedFx as a plain E1.31 device with more than 170 pixels, the WLED docs say to set "Universe Size" to 510 in its additional settings. LedFx's own WLED device already uses 510 when you switch its sync mode to E131.

What this setup does not do

Minotor timed its animations from MIDI clock, 24 ticks per quarter note (rhythm theory), so the animations stayed locked to the sequencer's tempo. LedFx works from audio analysis, and WLED's audio-reactive effects take sound from a microphone, a line input or the network. Neither project documents a MIDI clock input. If following a DAW's clock matters more than reacting to the sound, the alternatives page covers Resolume Arena, which does follow MIDI clock and can send Art-Net to the same ESP32.

The ESP32 can also run without a computer. WLED has had audio-reactive effects in every official release since 0.15.0. With an I2S microphone such as an INMP441 on the board, the 2D effects run on the ESP32 itself, using the same layout you set up above.

Sources

Read on 8 October 2026:

WLED documentation at kno.wled.ge: Quick Start, Install WLED Binary, Compatible Controllers, Wiring Guides, Settings, Ethernet, E1.31 / Art-Net, DDP and Audio Reactive
WLED v16.0.1 source at github.com/wled/WLED: the 2D and LED settings pages, bus_wrapper.h, FX.h and wled.h
LedFx documentation at docs.ledfx.app and the v2.2.1 source at github.com/LedFx/LedFx: devices/wled.py, devices/__init__.py and the effect modules

Release dates are from the GitHub API on the same day. If you run a Minotor wall this way and something here is wrong, write to hello@minotor.org.