Skip to content

Driving LED panels with a receiving card

You bought a panel receiving card, most likely a ColorLight one, the family MoonLight supports. The steps are in Drive LED panels through a receiving card, with Set the panels up in LEDVision and Clear the v13 flicker beside it. Below is what those steps lean on: why the link matters, which board, what the settings mean, and what to check when the wall stays dark.

New here? Start with Install MoonLight, then How MoonLight works.

1. What you actually bought

An LED wall is normally driven by two boxes. A sending card (a PCI-E board in a PC, or a standalone unit) takes video in and puts a specialised signal on Ethernet. A receiving card sits in each cabinet, decodes that signal, and drives the panels over HUB75 ribbon cables. The card you bought is a receiving card.

MoonLight takes the sending card's place. The board renders the effect and emits the frames itself, so there is no PC in the installation and no sending card to buy.

That has one consequence worth understanding before you wire anything: these frames are raw Ethernet, below IP. No address, no port, no DHCP. The cable between your controller and the card is not a network in the usual sense; it is a private link carrying pixel data, and nothing else should be on it.

Supported: ColorLight 5A-75 (5A-75B and 5A-75E use the same wire format).

2. What you need

Part Notes
ColorLight 5A-75 receiving card The one this guide is about
HUB75 panels Any size; you tell MoonLight the geometry later
5 V power supply Sized from the panels' own rating: see the note on power in §5
Cat5e or Cat6 cable Controller → the card's input port
A controller An ESP32 board (§3) or a desktop/Pi (§6)
A gigabit switch Only if your controller is a P4 or an S3, whose Ethernet is 100 Mbit: the switch lets the card negotiate a gigabit link on its own side and re-times the frames toward it. It does not make the controller faster: the 100 Mbit leg and its wire time (§2) remain, so a large wall still wants an S31. An S31 is gigabit already and connects straight to the card.
A USB gigabit Ethernet dongle Recommended on Windows. Not for MoonLight, which drives these cards fine from a built-in port, but for LEDUpgrade: if it cannot find the card through your built-in adapter, a dongle is the known way through. See §7.

The one hardware fact that decides everything

These cards want a 1 Gbit link. Not for bandwidth, since a 256×256 wall at 40 fps is only about 65 Mbit/s, which 100 Mbit would carry comfortably. It is about wire time.

The cards have no buffering and no flow control. They latch the image when the sync frame arrives, so an entire frame has to land inside the gap between frames. At gigabit a 256×256 frame is ~1.6 ms on the wire; at 100 Mbit the identical bytes take ~16 ms, which overruns the budget and breaks the timing the latch depends on.

The failure mode is the confusing part: nothing errors. The link is up, frames go out, and the panels tear, show wrong rows, or never latch. That is why MoonLight reads the negotiated speed and warns you, rather than letting a slow link look like a format bug. It still sends, since a small wall on 100 Mbit is often fine, but if your picture is unstable, check this first.

The cards can also be picky about negotiating a gigabit link with a 100 Mbit controller. A gigabit switch in between is the remedy: the card negotiates gigabit with the switch, the switch buffers, and the controller's slower link stops being the card's problem. This applies to the P4 and the S3. An S31 is gigabit on its own and connects directly.

3. Pick a board

Board Link Verdict
ESP32-S31 (Function-CoreBoard-1) 1 Gbit (YT8531) The right board. On-chip EMAC at gigabit is exactly what these cards want.
ESP32-P4 (Waveshare P4-NANO) 100 Mbit (IP101) Works for a small wall. A gigabit switch in between is reported to help. Use the -eth-wifi firmware: the Ethernet port is carrying panel data, so WiFi is how you reach the UI.
ESP32-S3 (DevKitC-1, N16R8 or N8R8) 100 Mbit over SPI (W5500 module) The board most people already own, and a real way to try a small panel before buying an S31. The slowest of the three: budget for a gigabit switch in between.

Other ESP32 variants do not ship panel-card support: their Ethernet is 100 Mbit at best, and most have none at all.

The S3 needs a W5500 Ethernet module wired to its SPI pins, which the S3 firmwares already support; its pins come from the board entry in deviceModels.json. Because W5500 is 100 Mbit and sits behind SPI, it is the configuration most likely to need the gigabit switch described in §2.

The panel-card firmware is already on for these boards. A classic-ESP32 build does not offer the driver at all.

4. Describe the wall

The driver has no geometry controls. The wall's shape lives in the Layout, once, so that everything else (effects, modifiers, the preview) sees the same picture.

A plain Grid is usually all you need. Two 128x64 panels stacked is a 128x128 grid, and that is the whole configuration. The reason it is that simple is worth knowing: the driver reads only the wall's width and height and sends the image row by row. Which physical panel a row lands on, and in what order the HUB75 ribbons chain, was already settled on the card in LEDVision. The card owns panel arrangement; MoonLight owns the picture.

That is also why this needs none of the physical detail you may have filled in elsewhere. An output page that asks for scan rate, address lines and chain order is describing panels driven directly, where the software has to generate the HUB75 timing itself. Through a receiving card, none of that is the sender's business: the card generates the timing, and the sender hands it an image. That holds for any sender, FPP included, which reaches these cards over Ethernet exactly as MoonLight does.

When you need the Panels layout instead. It exists for walls where MoonLight, not a card, owns the ordering: addressable panels wired as one long pixel strip, where the strip snakes from panel to panel and the layout has to undo that. Its controls are about wiring order, which a HUB75 ribbon does not have.

Control Meaning
horizontalPanels / verticalPanels How many panels across and down (1-32 each)
panelWidth / panelHeight One panel's pixels (default 16x16)
wiringOrder, X++, Y++, snake How pixels run within a panel
wiringOrderP, X++P, Y++P, snakeP How the panels themselves are ordered

Do HUB75 panels snake? Not in the sense these controls mean. A HUB75 panel is addressed by row and column over the ribbon, so its internal pixel order is fixed by the panel's own driver ICs and is not something a layout re-maps. A chain of panels can be arranged in any order, including a serpentine one, but that is configured on the card, not here. So if you are driving panels through a receiving card and every other row looks reversed, the setting to revisit is in LEDVision.

The interface control is ignored on an ESP32, which has one MAC. fps of 40 is a good start (1-120), and start and count stay at their defaults unless one picture is split across several controllers.

5. Power, WiFi and the status line

On powering panels from the same supply as the board. This works, and plenty of small setups run that way. What it costs you is headroom.

HUB75 panels draw far less than a naive count suggests, and the reason is multiplexing: the panel lights one group of scan rows at a time, cycling fast enough to look continuous, so at 1/16 or 1/32 scan only a fraction of the LEDs are on at any instant. This is why these panels have a reputation for modest consumption. Size the supply from the rating on your panel's own datasheet rather than from pixels multiplied by LED current.

The failure when you do run short is not a clean one: the 5 V rail sags, and a sagging rail shows up as flicker, color shifts, or the controller resetting mid-frame. None of those look like a power problem, which is why they cost an evening. A wall that is stable at 30% brightness and misbehaves at 100% is telling you this is the problem, not the network.

That is also how you reach the UI. The board's Ethernet port is now carrying panel data, so WiFi is what serves the web interface. Leave WiFi configured as normal; it is unrelated to the panel link and the two do not interfere. On the P4 this decides which firmware to flash, because the -eth variant has no WiFi compiled in at all: use -eth-wifi. The S31 and S3 firmwares carry both already.

The status line tells you what the wire is doing:

Status Meaning
1000 Mbit - 5200 packets/s Working. At the default v12 and older the rate is (rows + 2) × fps: one packet per row plus one brightness and one sync per frame, so 128 rows at 40 fps is 5,200. On v13 and newer both extras go out twice, (rows + 4) × fps = 5,280. A row wider than 497 pixels splits into several packets, so a wide wall sends more than one per row.
100 Mbit - … (warning) Sending, but see §2: fine for a small wall, tearing on a large one.
no ethernet link Cable, card power, or the wrong port on the card.

6. From a desktop

A PC, a Mac or a Raspberry Pi drives the same card with the same Layout and driver, for far more compute. Two things differ. interface must name the NIC the frames leave from. Raw Ethernet needs permission: sending below IP is privileged on every desktop OS, and without it the driver warns and records frames instead of sending them, which is also how the tests run with no hardware.

6.1 Windows

Windows has no built-in way for an application to put a raw Ethernet frame on the wire. That is an OS restriction, which is why Wireshark bundles a driver and why LEDVision needs one. Npcap is the maintained choice; legacy WinPcap 4.1.3 also works and is what this driver was measured against. MoonLight loads it at run time, so it installs without either, and the driver says so when you bind with none.

Windows names its capture devices \Device\NPF_{…GUID…}, so MoonLight matches your interface text against the adapter description instead. The full device name also works.

6.2 Linux, including Raspberry Pi

Raw frames go out over AF_PACKET, which needs CAP_NET_RAW. The kernel name goes in interface.

6.3 macOS

Raw frames go out over BPF (/dev/bpf*), root-only by default. Wireshark's ChmodBPF helper is the tidier option for regular use. On an Apple Silicon or Intel Mac the built-in port is usually gigabit and a USB-C dongle may not be, so check the status line rather than assuming.

7. Card firmware, and the flicker

A card's firmware has a version of its own, separate from the hardware revision printed on the board. It matters twice: once because one generation is defective, and once because MoonLight has to know which generation it is talking to.

The v13 flicker

Cards running firmware v13 on v8.x hardware flicker in time with network activity. This is a defect in the card, not in the sender: it shows up identically under MoonLight, FPP and ColorLight's own LEDVision, and nothing about how the frames are sent avoids it. The fix is to put older firmware on the card.

To be clear about what is and is not wrong: MoonLight drives a v13 card perfectly well. It binds, sends at the full frame rate, and the picture is correct. The flicker is the only reason to move off v13, and it is the card doing it. Since the trigger is network activity and driving a wall means constant network activity, there is no sending-side setting that avoids it. Batching, frame rate and packet count have all been tried; the defect is downstream of all of them.

Two different faults look like "flicker", and only one of them is this. Tell them apart before spending an evening on the wrong one:

What you see What it is
Flicker follows the Ethernet activity LED, and is there even on a still, dim image The v13 defect. Downgrade the card.
Flicker grows with brightness and with how much of the wall is lit Power. The panels draw more than the supply holds. A downgrade changes nothing.

The second row is worth taking seriously, because MoonLight sends a full frame every tick no matter what the effect is doing. The packet rate is identical for a black wall and a busy one, so flicker that tracks content is not coming from the network.

Which firmware to move to

Use LEDUpgrade 4.0 and firmware 11.09. 11.09 ships inside LEDUpgrade 4.0, so there is no firmware file to find. Version 5.0 ships no pre-v12 firmware, so it cannot do this downgrade. Anything before v12 clears the flicker, but 11.08 was reported strobing white, which 11.09 fixes. 11.09 is the newest build on the safe side of the defect. The steps: Clear the v13 flicker.

On Windows, if LEDUpgrade cannot find the card. A built-in Ethernet port can be held by something else in the stack, and Hyper-V's virtual switch is the usual culprit: it binds the adapter, so a tool that needs raw layer-2 access reaches nothing. A USB gigabit Ethernet dongle is the reliable way through. MoonLight's own sending works from a built-in port.

Then tell MoonLight what it is talking to

Set the driver's firmware control to match the card:

Setting For
v12 and older The default, and a downgraded card. Brightness and sync go out once.
v13 and newer A stock card. Both go out twice, which is the copy this firmware acts on.

The default is the downgraded generation on purpose: a v13 card is best moved off v13, so the setting is already right when you finish rather than being one last unexplained step.

The mismatch is not subtle in one direction: leave a downgraded card on v13 and newer and it receives a second sync, treats it as another latch, aborts the refresh already running, and the wall updates once every few seconds.

8. When it does not light up

Symptom Look at
no ethernet link On a desktop, check interface first: a string that matches no adapter fails the bind and reports exactly this, with nothing to distinguish it from an unplugged cable. Then cable seated, card powered, and plugged into the card's input port. On a 100 Mbit controller, try a gigabit switch in between.
Status healthy, panels dark The Layout, not the driver. If the wall is 0 lights, or the driver's window (start/count) selects none, there is nothing to send.
Image tears or rolls Link speed (§2). Check the status line says 1000 Mbit.
A new frame only every few seconds firmware (§7) is set to v13 and newer on a card running v12 or older. The duplicate sync latches twice and aborts the refresh.
Flicker in time with network activity The card's own v13 firmware defect (§7), not the sender. Downgrade the card.
Every other row or column mirrored With a receiving card, this is the card's own panel configuration: revisit it in LEDVision (LEDVision). The layout's snake / snakeP apply only to walls wired as a pixel strip.
Panels in the wrong places Same: the chain order is set on the card.
Right image, wrong colors fixture on the driver, which is where channel order and RGBW synthesis live for every driver. There is no separate color-order control here.
Works on ESP32, not on desktop Permission (§6). The driver shows a warning that says so.
PanelCard is not in the Drivers list The driver is compiled only into firmwares for boards with Ethernet (S3, P4, S31), so a classic-ESP32 build does not offer it. Only the S31 is gigabit; the S3 and P4 are 100 Mbit. Check the Firmware page for the variant and version you are running: an OTA upgrade keeps the installed variant, so a device first flashed with a different one keeps that one. Re-flash from the web installer to change variant.
Link is up and packets are on the wire, but the wall stays dark The frames are leaving correctly, so the fault is downstream of the send. Check, in order: global brightness and the driver's own localBrightness, both of which must be up; a layout actually configured and an effect selected, since an empty layer sends valid black frames; and format / firmware matching the card (§7). If all of that is right, remove the PanelCard driver and add it again: a re-add re-runs the bind and the geometry from scratch.

Where to go next