LED Matrix Panel — KiCAD plugin

Design custom addressable‑LED panels in seconds, right inside the KiCAD PCB editor. Pick a shape, pick an LED, and the plugin places every LED in data‑chain order, wires the DIN→DOUT daisy‑chain (plus the WS2815 backup line), distributes power, drops a decoupling cap next to each LED, and draws the board outline.

A pcbnew action plugin (toolbar button) for KiCAD 8 / 9 / 10, installable through the Plugin & Content Manager.

---

Features

• Shapes
  • Rectangular grid — rows × columns, independent X/Y pitch.
  • Parallelogram — a sheared grid at any skew angle.
  • Circular — concentric rings (auto LED‑count per ring from an arc pitch, or a fixed count) or a single Archimedean spiral.
• Data chain ordering — serpentine (snake) or progressive, row‑ or column‑major, from any start corner; rings/spirals are ordered center‑out.
• Data routing — draws the DIN→DOUT tracks in chain order.
• WS2815 backup line — for dual‑signal parts, also routes DOUT[n] → BIN[n+2] on a separate layer so the chain survives a dead LED.
• Power — copper pours (GND on one layer, LED‑supply on another) and/or tracks; separate 12 V (VDD) and 5 V (VCC) rails handled for WS2815.
• Decoupling caps — one bypass cap per LED, auto‑placed and net‑tied.
• Board outline — Edge.Cuts matching the panel shape (rectangle, circle, parallelogram).
• Any LED — presets for common parts, or supply your own footprint and a pad→function map.
• Live preview of the LED count as you change parameters.

Two modes

The plugin can build a panel two ways (chosen at the top of the dialog):

• Generate — creates the LED footprints from a library and routes them. Fastest; schematic-less (no ERC/BOM). Great for quick panels.
• Replicate — you draw one LED in a hierarchical sheet, instantiate it N times, import to the PCB, then lay out and route one instance. The plugin repositions the other instances into the chosen shape, clones the source unit's tracks/zones into each (remapping nets by pad-matching, so it stays consistent with the schematic), and routes the schematic-defined data chain + backup + power between units. Keeps a proper schematic (real ERC/BOM) and your careful per-LED routing. This is the "design one unit, stamp the panel" workflow — like ReplicateLayout, but driven by the shape engine instead of hand-placed anchors.

Supported LEDs

Preset	Footprint (KiCAD LED_SMD)	Notes
WS2812B (5050)	LED_WS2812B_PLCC4_5.0x5.0mm_P3.2mm	1=VDD 2=DOUT 3=GND 4=DIN
WS2812B‑2020	LED_WS2812B-2020_PLCC4_2.0x2.0mm	different order: 1=DOUT 2=GND 3=DIN 4=VDD
WS2812B‑Mini	LED_WS2812B-Mini_PLCC4_3.5x3.5mm	assumed WS2812B map
SK6812 (5050)	LED_SK6812_PLCC4_5.0x5.0mm_P3.2mm	1=GND 2=DIN 3=VDD 4=DOUT
SK6812 OPSCO	LED_OPSCO_SK6812_PLCC4_5.0x5.0mm_P3.1mm	same numbering as SK6812
WS2815 (12 V, dual‑signal)	LED_WS2812_PLCC6_5.0x5.0mm_P1.6mm †	1=VCC 2=VDD(12V) 3=DOUT 4=DIN 5=GND 6=BIN
Custom	(you provide)	any footprint + 1=VDD,2=DOUT,… pad map

† KiCAD ships no dedicated WS2815 footprint; the PLCC6 WS2812 body matches and KiCAD's WS2813 symbol already carries this exact pin map. Verify the pin‑1 corner against your WS2815 mechanical drawing before ordering.

Because the plugin routes by pad function (looked up from the map) and reads each pad's real position at build time, the different pad numberings above — including SK6812 being numbered as if rotated 180° — are handled automatically.

Installation

Via the Plugin & Content Manager (recommended)

1. Build the package (or download a release .zip):

   python build.py
   # -> dist/LedMatrixPanel-<version>-pcm.zip

2. In KiCAD: Plugin and Content Manager → Install from File… and pick the .zip.
3. Open the PCB editor. A new LED Matrix Panel button appears on the toolbar (and under Tools → External Plugins).

You can also host dist/repository.json and add it as a custom PCM repository — see docs/USAGE.md.

Manual install

Copy the plugins/ folder into your KiCAD 3rd‑party plugins directory, renamed to a unique folder name, e.g.:

• Linux: ~/.local/share/kicad/10.0/3rdparty/plugins/LedMatrixPanel/
• Windows: %USERPROFILE%\Documents\KiCad\10.0\3rdparty\plugins\LedMatrixPanel\
• macOS: ~/Documents/KiCad/10.0/3rdparty/plugins/LedMatrixPanel/

Then restart pcbnew (or Tools → External Plugins → Refresh).

Usage

1. Create/open a board (a fresh empty .kicad_pcb is fine — the plugin works without a schematic).
2. Click the LED Matrix Panel toolbar button.
3. Configure the panel across the tabs — Shape & Size, LED & Caps, Routing, Board — watching the Estimated LEDs count.
4. Click OK. The panel is generated on the current board; a summary dialog reports what was placed and routed.

See docs/USAGE.md for every parameter, worked examples (8×8 grid, 12 V WS2815 ring, spiral) and the routing details.

How routing works

• Data chain — LEDs are numbered in traversal order; DOUT[i] and DIN[i+1] share a net named DOUT_D{i}. The very first DIN is the panel input net DATA_IN; the last DOUT is the panel output.
• WS2815 backup — BIN[i] joins the node that drives it two LEDs upstream (DOUT[i-2]); the first two backup inputs tie to DATA_IN. Backup tracks are drawn on a separate layer (default B.Cu) so they don't fight the primary data on F.Cu.
• Power — nets are defined by role: every VDD pad → the LED‑supply net, every VCC pad → the logic‑supply net (WS2815 only), every GND pad → GND. In zones mode the high‑current LED‑supply and GND get copper pours on separate layers; the low‑current WS2815 logic rail is routed as tracks.
• Caps — each cap bridges the LED‑supply net and GND, with short stub tracks to its LED so it's connected even without pours.

Architecture

The layout logic is deliberately separated from the KiCAD API so it can be unit‑tested without KiCAD, and so a future port to KiCAD's new IPC API only touches one file.

Module	Depends on pcbnew?	Responsibility
plugins/geometry.py	no	shape math → ordered LED sites + outlines
plugins/led_types.py	no	LED presets + pad→function maps
plugins/config.py	no	the PanelConfig data model + validation
plugins/planner.py	no	full routing plan (nets, tracks, zones, caps)
plugins/replicate_core.py	no	unit ordering + rigid-transform math
plugins/kicad_api.py	yes	thin, version‑tolerant pcbnew wrapper
plugins/board_builder.py	yes	applies the plan to the board (Generate)
plugins/replicate.py	via api	stamps a laid-out unit into the shape (Replicate)
plugins/dialog.py	wx	the configuration GUI
plugins/action.py	pcbnew/wx	the toolbar action

Development

python tests/run_all.py     # run the suite with plain Python (no deps)
# or, if you have pytest:
pytest -q

python tools/make_icons.py  # regenerate the icons (no image libs needed)
python build.py             # build the PCM package into dist/

The tests cover the geometry engine, the routing planner (including the WS2815 backup topology), a full Generate build, and a full Replicate run (unit matching, transforms and net‑remapping) against an in‑memory pcbnew mock — so most of the plugin is exercised without launching KiCAD.

Notes & limitations

• Generate mode is schematic‑less by design. It creates footprints directly, so the board has no netlist‑from‑schematic and schematic sync will report the LEDs as unknown — expected for a standalone panel. If you want a real schematic (ERC/BOM), use Replicate mode with hierarchical sheets.
• Replicate mode does not edit the schematic (KiCAD has no schematic scripting API); it only arranges/routes the footprints your schematic already produced. The inter‑unit data chain is routed only where the schematic already connects it — unconnected pairs are reported, not invented.
• Auto power/data tracks are a starting point — they're straight point‑to‑point segments and may cross on dense/curved panels. Copper pours (the default for power) are the robust choice for current; review and clean up data tracks as needed, then run DRC.
• Verify part pinouts, especially WS2815 pin‑1 orientation, against your manufacturer's datasheet before fabrication.
• Zone filling is attempted automatically; if it's skipped on your board, press B (Fill All Zones) in pcbnew.

License

MIT — see LICENSE.