Plasma-DMD/CLAUDE.md

Plasma DMD — notes for Claude

The goal: drive a second-hand 128×32 pinball plasma DMD panel standalone from a Wemos D1 mini ESP32, powered from 12 V DC only. The panel was originally on a Williams WPC controller and was bought on 2021-09-18 for €37. No original controller or PSU came with it.

Status (keep this section up to date)

• PAUSED (2026-10-24) at the user's request, because of the cost and the safety risk. If resuming, consider the cheaper, no-high-voltage alternative discussed: a 128×32 HUB75 LED matrix driven by the same ESP32 (about €30–50).

• Design docs in docs/, PSU schematic and routed PCB rev 0.1 in hardware/kicad/, firmware skeleton in firmware/.

• Not yet known: the panel's make and part number, its power and data connector pinouts, and the polarity of its control signals. J2's pinout is a placeholder (Stern CN2 order).

• Nothing is built or tested on real hardware.

• Proposed rev 0.2: module-only PSU (no linear regulators or heatsinks), reviewed in docs/design-review.md. It's waiting on the must-fix items M1–M4 there. The schematic and PCB are still rev 0.1.

Design decisions (don't silently change these)

• PSU:
  • A 12 V brick feeds a Mini560 (5 V) and two NCH6100HV boost modules: one at 90 V, and one at 130 V fed through an isolated DC-DC, so its output floats and becomes −130 V.
  • Those raw rails feed a copy of the regulator section of the Stern 520-5138-00 (zener-referenced followers), giving about +65 V, −112 V and −100 V.
  • The zeners set the panel voltages, not the module trim pots.
• Modules sit off-board on screw terminals. The PCB is a carrier board.
• Safety first:
  • A relay switches the 12 V feed to the HV modules.
  • The relay is driven by a hardware charge-pump watchdog, toggled by GPIO21 once per scanned row (about 2 kHz). If toggling stops, the HV drops.
  • Bleeders and fuses on every HV rail.
• Clearances (hardware/kicad/plasma_dmd_psu.kicad_dru):
  • 3 mm between HV and LV, 1.3 mm between HV nets.
  • Documented exceptions only inside or next to transistor and connector pins.
• TO-220 tabs and heatsinks are live. Each heatsink pin is on its collector net.
• Track widths come from IPC-2221 against the fuse currents (see hardware/kicad/README.md).

Workflow and tools

• KiCad 10: C:/Users/patri/AppData/Local/Programs/KiCad/10.0/bin/ (kicad-cli.exe, and python.exe with pcbnew).
• Freerouting 2.5.0 jar: tools/freerouting/, git-ignored. It needs Java 25: C:/Program Files/Eclipse Adoptium/jre-25.0.4.101-hotspot/bin/java.exe.
• Pipeline (KiCad must be closed while the scripts run):
  1. python hardware/kicad/gen_kicad.py writes the schematic and the project net classes from PARTS. It keeps symbol UUIDs, so the PCB stays linked.
  2. python hardware/kicad/check_netlist.py verifies every pin's net through kicad-cli.
  3. <kicad python> hardware/kicad/layout_pcb.py adds, swaps and places footprints from PLACE and draws the outline and silkscreen. It deletes tracks and zones.
  4. <kicad python> hardware/kicad/route_pcb.py [passes] runs Freerouting:
     • It routes with oversized tracks and vias, then shrinks them, which yields the clearances.
     • It adds J2 escape stubs and heals T-junctions.
     • It adds the bottom GND pour.
  5. kicad-cli pcb drc --schematic-parity --refill-zones hardware/kicad/plasma_dmd_psu.kicad_pcb. The target is 0 errors. The 9 silkscreen warnings (TO-220 outline over the heatsink pins) are known.
• Once the user starts hand-editing the schematic or PCB in KiCad, stop regenerating with the scripts.

Gotchas learned the hard way

• Bash heredocs passed through the tool can collapse \\ and \n escapes. For Python with regexes or escapes, use the Write/Edit tools, not python - <<EOF.
• pcbnew: use board.Delete(item), not Remove (Remove leads to segfaults). GetTracks() throws TypeError when empty. Copy coordinates out of an item before deleting it.
• KiCad schematic text needs \n escapes, not raw newlines, or the file won't load.
• Freerouting puts fixed stubs back in the SES (duplicates). Its SES can silently omit a net when routing is incomplete, so always check DRC for unconnected pads.
• MKDS terminal blocks: wire entry is on the footprint's +y side.

User preferences

• Commit only when the user asks. Initial commit dbc1f00, PCB rev 0.1 28c6665. Remote: origin = https://mangavalk.com/mangavalk/Plasma-DMD.git (branch main).
• Before changing a file the user may have edited, check their edits first and keep them.