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`. The repo has no remote.
- Before changing a file the user may have edited, check their edits first and keep them.