Pcb Review

BOM/CPL/PCB cross-check (verify_bom_cpl_pcb.py, 13 checks): Verifies all designators match across BOM, CPL, and PCB. Checks footprint names are JLCPCB-compatible, CPL rotations valid, positions match (with known correction allowances), all LCSC part numbers present, and schematic field completeness.

JLCPCB capabilities (verify_jlcpcb_capabilities.py, 12 checks): Two-tier cross-check against JLCPCB published manufacturing limits. FAIL = board rejected, WARN = below recommended. Covers trace, via, THT, clearance rules.

Stencil aperture (verify_stencil_aperture.py, 6 checks): IPC-7525 area ratio + aspect ratio for multiple stencil thicknesses (3-5mil), paste powder type recommendation, fine-pitch component detail report.

Drill standards (verify_drill_standards.py, 6 checks): ISO metric + JLCPCB common drill mapping, drill inventory count, IPC-2222 drill-to-pad ratio, via vs PTH appropriateness.

1b. Run extended verification suite (17 gap-coverage tests)

# High-risk (5 tests)
python3 scripts/verify_antenna_keepout.py
python3 scripts/verify_stackup.py
python3 scripts/verify_net_class_widths.py
python3 scripts/verify_bom_values.py
python3 scripts/verify_power_paths.py

# Medium-risk (7 tests)
python3 scripts/verify_copper_balance.py
python3 scripts/verify_decoupling_paths.py
python3 scripts/verify_usb_impedance.py
python3 scripts/verify_via_in_pad.py
python3 scripts/verify_thermal_relief.py
python3 scripts/verify_ground_loops.py
python3 scripts/verify_test_points.py

1c. Run datasheet verification (electrical + physical)

python3 scripts/verify_datasheet_nets.py
python3 scripts/verify_datasheet.py

Datasheet net verification (verify_datasheet_nets.py, 246 checks): Compares EVERY pad of EVERY component against the expected net from the datasheet. Uses hardware/datasheet_specs.py as single source of truth (pin→net mapping).

• Catches: unconnected pads that should be connected, wrong net on a pad
• Example: USB-C pad 1 should be GND, shield pads should be GND, VBUS on all 3 pins

Datasheet physical verification (verify_datasheet.py, 29 tests): Compares PCB footprint dimensions against datasheet mechanical drawings.

• Pin count per component (ICs, connectors, passives, switches)
• Pad pitch (0.5mm FPC, 1.27mm SOIC, 2.0mm JST, etc.)
• Pad span / body dimensions (catches wrong package, e.g. SOP-16 vs SOIC-16W)
• NPTH positioning hole count and drill sizes
• THT drill sizes (JST, USB shield tabs)
• Datasheet PDF presence in hardware/datasheets/

1f. Run design intent adversary (cross-source consistency)

python3 scripts/verify_design_intent.py

Design intent verification (verify_design_intent.py, 362 checks): Cross-checks GPIO assignments, net connections, and signal paths across ALL sources: firmware (board_config.h), schematic config (config.py), datasheet specs, and actual PCB layout.

1g. Run DRC Audit (electrical connectivity)

kicad-cli pcb drc \
  --output /tmp/drc_audit_report.json \
  --format json \
  --severity-all --units mm --all-track-errors \
  hardware/kicad/esp32-emu-turbo.kicad_pcb

CRITICAL step — catches issues that ALL custom scripts miss:

• shorting_items: traces touching pads with wrong/no net (board malfunction)
• unconnected_items: broken signal paths (components not connected)
• via_dangling: orphan vias (wasted manufacturing, DFM warnings)
• clearance: real spacing violations below JLCPCB minimums

Our verify_dfm_v2.py runs KiCad DRC but only checks 3 of 9 violation types. Test 43 (trace-pad clearance) auto-skips when pads lack net assignments. This step fills that gap. See .claude/skills/drc-audit/SKILL.md for full methodology.

Classify shorting_items as:

• Real shorts ("nets X and Y)") — CRITICAL, board will fail
• Pad-net bugs ("nets X and )") — generator fix needed in _init_pads()

1d. Run ERC (Electrical Rules Check)

python3 scripts/erc_check.py --run

Runs KiCad native ERC on the hierarchical schematic. Categorizes 730+ violations:

• Generator artifacts (suppressed): grid alignment, wiring stubs, library symbols — inherent to Python-generated schematics
• Real issues: pin_not_connected, power_pin_not_driven, pin_to_pin conflicts
• Critical: pin_to_pin (output↔output) must be zero for production

1e. Run SPICE power supply simulation

python3 scripts/spice_power_check.py

Requires: ngspice (brew install ngspice)

Simulates IP5306 boost → AMS1117 LDO → ESP32 load:

• +5V rail ripple at 500kHz switching (must be < 150mV)
• +3V3 rail ripple under load steps (must be < 50mV)
• Decoupling cap effectiveness (C17, C27, C1, C19)
• ESP32 WiFi burst response (200mA → 350mA in 10µs)

1j. Run electrical review scripts

# Strapping pin verification (12 tests)
python3 scripts/verify_strapping_pins.py

# Decoupling capacitor adequacy (25 tests)
python3 scripts/verify_decoupling_adequacy.py

# Power sequencing verification (26 tests)
python3 scripts/verify_power_sequence.py

1k. Run connectivity and signal chain verification

# Component connectivity — catches phantom BOM components (2 tests)
python3 scripts/verify_component_connectivity.py

# Signal chain completeness — catches broken copper paths (53 tests)
python3 scripts/verify_signal_chain_complete.py

1l. Run net classification and board config validation

# Net function classifier — validates GPIO-to-net name consistency
python3 scripts/net_classifier.py --validate

# Board config drift detection — config.py vs board_config.h
python3 scripts/generate_board_config.py --check

1m. Run schematic-to-PCB netlist diff

python3 scripts/verify_netlist_diff.py

Netlist cross-check (verify_netlist_diff.py, 4 checks): Exports schematic XML netlist via kicad-cli, compares against PCB cache:

• Missing routes (schematic net not in PCB)
• Orphan PCB nets (PCB net not in schematic)
• Missing footprints (component in schematic but not PCB)
• Pin-to-net mismatches between schematic and PCB

1m2. Run schematic↔PCB/datasheet_specs sync guard (R4 class)

python3 scripts/verify_schematic_pcb_sync.py

Schematic/PCB/datasheet_specs.py sync (verify_schematic_pcb_sync.py): Guards against the R4 class of bugs — schematic generator and PCB generator are two independent Python code paths and can drift silently. Three checks, all fail-loud (no soft-passes, no auto-skip):

CRITICAL — this script must exit 0 before any PCB release. It is the only guard that catches schematic↔PCB drift on the Python generators. Never add suppressions; never edit the allowlist in the script to make a real bug disappear. Fix the design side instead.

1n. Generate hardware test firmware (Phase 3 prototype)

python3 scripts/generate_hw_tests.py

Hardware test generator (20 tests in software/test/test_hardware.c): Auto-generates ESP-IDF Unity test firmware from board_config.h:

• 12 button idle-HIGH tests (BTN_L internal pull-up)
• LCD D0-D7 walking-1 short detection
• SD SPI bus init + CMD0 probe
• I2S PDM TX silence test
• USB JTAG verification
• 3.3V power rail ADC check
• PSRAM 1MB pattern verify

2. Manual review against checklist

Read review-checklist.md and verify each domain:

3. Datasheet physical verification

python3 scripts/verify_datasheet.py

Automated cross-check of PCB vs datasheets (29 tests):

• Pin count per component (ICs, connectors, passives, switches)
• Pad pitch matches datasheet (0.5mm FPC, 1.27mm SOIC, 2.0mm JST, etc.)
• Pad span / body dimensions (catches wrong package, e.g. SOP-16 vs SOIC-16W)
• NPTH positioning hole count and drill size
• THT drill sizes (JST, USB shield tabs)
• Datasheet PDF presence in hardware/datasheets/

3b. Manual datasheet verification (Domain 6)

For each IC/connector, read the datasheet from hardware/datasheets/ and verify:

• Pin 1 location matches footprint orientation
• Net assignments match datasheet pinout
• CPL rotation produces correct JLCPCB placement
• Passive component values match typical application circuit

4. Current capacity check (Domain 1)

Verify power trace widths against current requirements:

• VBUS/BAT+: up to 2.1A (IP5306 charger) → need ≥0.76mm (30mil)
• +5V: up to 1A → need ≥0.25mm (10mil)
• +3V3: up to 0.5A → need ≥0.13mm (5mil)
• LX (inductor): up to 2.1A pulsed → need ≥0.76mm (30mil)

1h. Run trace-through-pad overlap check

python3 scripts/verify_trace_through_pad.py

1h2. Run per-net copper connectivity check (R5-CRIT gate)

python3 scripts/verify_net_connectivity.py

CRITICAL HARD GATE (R6): walks the union-find over pads ∪ vias ∪ segments for every net and asserts single connected component. Catches the R5-CRIT class of bugs where pad-net labels are correct but copper is fragmented — L1.1 BAT+ inductor isolated (board can't boot on battery), C17/C18 decoupling caps floating, button pull-ups never connected, SW_BOOT non-functional, D1 menu diode anodes dangling, BTN_L missing F.Cu→B.Cu via-in-pad at U1.26 (L shoulder button never worked on v3.3). Run with --strict to bail on technical-debt accepted fragmentations.

CRITICAL HARD GATE: any overlap means a copper trace physically shares copper with an unnetted (or differently-netted) pad — a real short on the manufactured board. Checks F.Cu and B.Cu. Catches issues that DRC misses when pads have no net assignment (the v3.3 regression from commit 775e9fd, where _PAD_NETS entries for U2.3/4, U6.8/9, SW_PWR.4b/4d were removed and left BTN_SELECT/GND/SD_MISO/BTN_R traces crossing unnetted pads). Integrated into:

• make release-prep (blocking dependency of release)
• make verify-all (parallel verification suite)
• make verify-trace-through-pad (standalone)
• /release, /release-prep, /full-release skills (hard gate)
• Stop hook .claude/hooks/stop-verify-dfm.sh (auto-runs after any PCB edit and blocks Claude's response with exit 2 on failure)

1i. System health summary

Answer these 5 questions with data:

If ANY check fails, stop and fix before generating the report.

5. Generate report

Format findings as:

## PCB Design Review Report

| # | Domain | Score | Key Finding |
|---|--------|-------|-------------|
| 1 | Power Integrity | ?/15 | ... |
| 2 | Signal Integrity | ?/15 | ... |
| 3 | Thermal | ?/10 | ... |
| 4 | JLCPCB DFM | ?/20 | ... |
| 5 | EMI/EMC | ?/10 | ... |
| 6 | Component Polarity | ?/15 | ... |
| 7 | Mechanical | ?/10 | ... |
| 8 | Documentation | ?/5 | ... |
| **TOTAL** | | **?/100** | ... |

### Top 5 Priority Fixes
1. ...
2. ...

6. Fix and re-verify

After making changes:

python3 -m scripts.generate_pcb hardware/kicad
python3 scripts/verify_dfm_v2.py
python3 scripts/verify_polarity.py
python3 scripts/validate_jlcpcb.py

Key Files

• .claude/skills/pcb-review/review-checklist.md — Full scoring criteria + JLCPCB rules reference
• hardware/datasheets/ — Component datasheets for pin verification
• scripts/pcb_review.py — Automated review script
• scripts/verify_dfm_v2.py — DFM verification (115 tests)
• scripts/verify_polarity.py — Polarity/pin assignment tests
• scripts/verify_dfa.py — Assembly verification (9 tests)
• scripts/verify_bom_cpl_pcb.py — BOM/CPL/PCB cross-check (10 tests)
• scripts/verify_datasheet.py — Datasheet vs PCB physical verification (29 tests)
• scripts/verify_datasheet_nets.py — Datasheet vs PCB net/pinout verification (259 checks)
• hardware/datasheet_specs.py — Single source of truth: pin→net mapping for all 30 components
• scripts/validate_jlcpcb.py — JLCPCB manufacturing validation (26 tests)
• scripts/verify_antenna_keepout.py — ESP32 antenna zone clearance (5 checks)
• scripts/verify_stackup.py — 4-layer stackup net verification (5 checks)
• scripts/verify_net_class_widths.py — Power/signal trace width enforcement (5 checks)
• scripts/verify_bom_values.py — BOM vs schematic value cross-check (75 checks)
• scripts/verify_power_paths.py — Power delivery path tracing (19 checks)
• scripts/verify_copper_balance.py — Layer copper distribution (3 checks)
• scripts/verify_decoupling_paths.py — Cap-to-IC path quality (11 checks)
• scripts/verify_usb_impedance.py — USB D+/D- impedance geometry (4 checks)
• scripts/verify_via_in_pad.py — Via-in-pad detection all SMD pads (3 checks)
• scripts/verify_thermal_relief.py — Zone thermal relief settings (4 checks)
• scripts/verify_ground_loops.py — Audio-digital ground coupling (3 checks)
• scripts/verify_test_points.py — Debug probe accessibility (18 checks)
• scripts/erc_check.py — ERC automation (KiCad native, artifact filtering)
• scripts/spice_power_check.py — ngspice power supply simulation (+5V/+3V3 ripple, load transient)
• scripts/verify_design_intent.py — Cross-source adversary (362 checks, T1-T22)
• scripts/verify_netlist_diff.py — Schematic-to-PCB netlist cross-check (4 checks)
• scripts/verify_schematic_pcb_sync.py — R4 sync guard: ref coverage, designator collisions, connector net coverage (schematic vs datasheet_specs.py vs CPL)
• scripts/net_classifier.py — Net function classifier with GPIO validation
• scripts/generate_board_config.py — Board config drift detection (config.py vs board_config.h)
• scripts/generate_hw_tests.py — ESP-IDF Unity test generator (20 tests)
• scripts/generate_pcb/routing.py — Trace routing
• scripts/generate_pcb/board.py — Component placement
• scripts/generate_pcb/jlcpcb_export.py — CPL/BOM export