rebbarb/hardware/re-bba-rb/TODO.md

# re-bba-rb board — open items from hardware review (2026-07-17)

Full review of schematics + PCB against component datasheets
(`datasheets/` — restore from commit `db457a0`, see Housekeeping), the WIZnet
W5100S reference schematic, and JLCPCB manufacturing limits. ERC/DRC: clean.

## Critical — must fix before (or with) next fab

- [x] **EXI DO/DI swapped at J3 — FIXED 2026-07-17** (all copper unchanged).
      YAGCD SP1 naming is console-perspective: pin 6 `DO` = GC data **out** →
      adapter's MOSI *input*; pin 9 `DI` = GC data **in** ← adapter's MISO
      *output* (verified via SD Gecko: MC pin 5 DO → SD CMD input; SD2SP2:
      DO → OR gate → SD CMD). Fix applied as a pure rename/identity swap:
      - [x] SP1 pin table in `docs/gc_bba_fpga_design.md` corrected (was the
            root cause) + MISO-tristate note updated.
      - [x] Net names EXI_MOSI(_RAW) ↔ EXI_MISO(_RAW) swapped across
            `exi.kicad_sch`, `Fpga.kicad_sch`, root sheet, and the PCB — this
            also swaps the D2 (PUSB3AB6) channel assignments by name.
      - [x] R21 (22 Ω) ↔ R25 (33 Ω) identities swapped between the two
            positions so 33 Ω stays on the FPGA-driven MISO line and 22 Ω on
            the MOSI input.
      - [x] Verified: ERC 0, DRC 0 (incl. schematic parity 0), netlist:
            J3.6(DO)→R21(22Ω)→**FPGA pin 4 (IOB_8a) = EXI_MOSI in**;
            J3.9(DI)→R25(33Ω)→**FPGA pin 3 (IOB_9b) = EXI_MISO out**.
      - [ ] Use this final pin map when writing the board PCF (see Broader
            items): MOSI = pin 4, MISO = pin 3, CLK = 44 (G6), CS = 45,
            INT = 46.
- [ ] **W5100S MDI termination network missing** (`ethernet.kicad_sch`).
      Per WIZnet W5100S reference schematic: 49.9 Ω from each of
      TXOP/TXON/RXIP/RXIN to a common node with 0.1 µF to GND, placed near the
      chip ("to avoid the 100M overshoot"); optionally 3.3 Ω series damping in
      each line. Board routes the pairs straight through D4/D5 to the magjack.
      - [ ] Add 4× 49.9 Ω 1% + 2× 0.1 µF termination.
      - [ ] Place C51/C52 physically at J2 pins 4/5 (center taps).
      - [ ] Reconsider D4/D5 (USBLC6 on the line side of the magnetics):
            unusual — transformer already isolates; their VBUS pins float so
            they only clamp to GND. Remove or justify.
- [ ] **FT2232H EEPROM interface** (`Usb Connector.kicad_sch`): datasheet
      Table 3.4 requires EEDATA → 93LC46B **DO via 2.2 kΩ** plus **10 kΩ
      pull-up on DO to VCC** (DI stays direct). Board ties DO and DI both
      directly to EE_DATA → read contention, unreliable EEPROM enumeration.

## Functional / robustness

- [ ] **iceprog pin mismatch**: iceprog hardcodes CS=ADBUS4, CDONE=ADBUS6,
      CRESET=ADBUS7. Board uses FLASH_CS=ADBUS3, CDONE=ACBUS1, CRESET=ACBUS0.
      Rewire to the iCEbreaker convention, or maintain a patched iceprog.
- [ ] **TPS2116 PR1 divider margin**: 200k/100k gives PR1 = 1.10 V vs
      VREF = 1.0 V ±8 % (max 1.08 V) — 20 mV worst-case margin against the
      3.3 V buck output. Change R3 to 150 k → switchover at 2.30–2.70 V.
- [ ] **ETH_RST pull-up**: W5100S RSTn is a plain input (no internal pull) and
      floats while the FPGA configures. Add 10 k to **ETH_3V3** (not 3V3, so
      it sits low when the ETH rail is off).
- [ ] **Gateware: gate all outputs on GC_ON** — when GC_ON=0 the W5100S is
      unpowered (U12) and the GC is off, but FPGA banks stay at 3.3 V. Hold
      the W5100S bus and EXI outputs Hi-Z/low to avoid back-powering.
- [ ] **Gateware: UART crossover** — net names are FT-perspective
      (UART_TXD = FTDI output = FPGA **RX** on pin 18). Get this right in the
      board PCF.
- [ ] **Gateware: EXI INT drive style** — prefer open-drain emulation (drive
      low / release) on J3.3 rather than push-pull high.

## Broader items (beyond the wiring review — block fab on the first two)

- [ ] **Write the re-bba-rb pin constraints** — `exi_bba/synth.py` still targets
      the iCEbreaker. This board: EXI on FPGA pins 3 (IOB_9b), 4 (IOB_8a),
      44 (EXI_CLK, G6), 45 (EXI_CS), 46 (EXI_INT); W5100S bus on the IOT bank
      (23–43); CLK12 on 20 (G3); GC_ON on 21; ETH_RST on 2; UART on 18/19.
      This is where the DO/DI swap and the UART crossover (UART_TXD = FTDI
      output = FPGA RX) get resolved. Pure software; do it before ordering to
      prove the pinout.
- [ ] **Add debug provisions — the board currently has none.** RGB0–2 are
      unconnected, no LEDs, no button, no test points; the CLAUDE.md bring-up
      plan (StatusPanel heartbeat/activity LEDs + BTN re-init) has nothing to
      drive. Spare IOBs: 6, 9, 10, 11, 12, 13, 47, 48. Add ≥2 LEDs (heartbeat,
      EXI activity), a 4–6 pin debug header (logic-analyzer access — EXI
      CLK/CS/MOSI/MISO are what you probe when enumeration fails), and test
      points on 3V3 / 1V2 / ETH_3V3 / GC_ON. Cannot be retrofitted.
- [ ] **Verify mechanical fit** — outline + finger geometry vs SP1ETH/ETH2SP1
      references (per CLAUDE.md), RJ45 and USB-C protrusion vs the GC serial
      port bay opening. An earlier commit says "need to remeasure PCB outline";
      sp1_test_plug validates pads only, not the envelope.
- [x] **SP1 12 V rail viability — VERIFIED against existing projects
      (2026-07-17).** webhdx's IDE-EXI v2 for Serial Port 1 (which became the
      commercial M.2 Loader): "New switching power regulator supplies 3.3V@2A
      from 12V rail" (webhdx, gc-forever thread t=4843, 2021-08-28) — a
      shipping SP1 product powers an M.2 SATA SSD + RP2040 entirely from
      pin 5's 12 V through a buck, no external supply. That's the same
      architecture as this board at several times our load (~130 mA @ 12 V).
      webhdx moved from a linear regulator to a buck because the linear "was
      generating a lot of heat" — validating the TPS562201 choice. The
      official modem (DOL-014) was the original 12 V consumer; SP1ETH leaves
      12 V unused (runs from the 3.3 V pins). Remaining bench check only:
      - [ ] inrush into C65 (100 µF) + 2×10 µF buck input caps at GC power-on
            (the M.2 Loader precedent suggests this is a non-issue).
- [ ] **Decide FT2232H EEPROM contents + flashing workflow** — blank 93LC46B
      enumerates with default VID/PID (works, generic); custom
      VID/PID/serial/product string needs FT_PROG provisioning. Tied to the
      iceprog-pin-mapping decision above (changes the schematic).
- [ ] CC1/CC2 have no ESD protection (USBLC6 covers D+/D− only) — optional,
      most hobby designs skip; note spare-channel budget if respinning D2 area.
- [ ] Ensure `hardware/re-bba-rb/.history/` (contains an embedded `.git`) is
      gitignored and never committed.

## Minor / BOM

- [ ] RSET_BG: datasheet says 12.3 kΩ 1 % (ref schematic: 12 k + 300 Ω);
      board has 12.4 k (~0.8 % off). Match if convenient.
- [ ] Crystals Y1 (FTDI 12 MHz) and Y2 (W5100S 25 MHz): 18 pF load caps are
      correct **only for CL ≈ 12 pF crystals** — pick parts accordingly
      (W5100S Table 9 recommends CL = 12 pF).
- [ ] 12 V-rail parts ≥ 25 V rating: C3, C4 (10 µF 0805), C6, C65 (100 µF
      electrolytic); D3 SMAJ12A already correct.
- [ ] 1 % tolerance required: R1/R2 (buck VFB divider, TI requirement),
      R10 (FTDI REF 12 k), R16 (RSET_BG), R3/R4 (PR1 divider).
- [ ] TPS22810 CT: floating = fastest ramp (~0.7 A inrush into ETH rail
      caps). Consider CT = 10 nF footprint (DNP-able).
- [ ] Verify HR911105A internal LED pinout (assumed: 9/12 anodes via
      R14/R15 330 Ω to ETH_3V3, 10/11 cathodes to LNKn/ACTn) and the
      Bob-Smith common on pin 8 (tied straight to GND here; WIZnet ref
      separates chassis via 1 nF/2 kV — acceptable choice, confirm intent).
- [ ] Confirm at bring-up (from CLAUDE.md): W5100S register addresses / MR
      bits were written from memory.

## JLCPCB ordering notes (DRC clean — these are order-form options)

- [ ] Stackup = JLC04121H-7628 (matches the 0.2104 mm prepreg / 0.6 mm core,
      ~1.14 mm ≙ JLC nominal 1.2 mm — satisfies the SP1 slot's 1.2 mm spec).
- [ ] Select **ENIG** (file has copper_finish "None") and **gold fingers +
      45° bevel** for the SP1 edge connector.
- [ ] Hand-solder / non-economic-assembly parts: C65 (THT electrolytic),
      J2 magjack (THT), J1 USB-C, D2 (DFN2111-7, tiny). Plan assembly split.
- [ ] Add LCSC part numbers to symbol fields for JLC PCBA BOM export; check
      fiducials for SMT.

## Housekeeping (repo) — done 2026-07-17

- [x] Restored `hardware/re-bba-rb/datasheets/` (deleted by `3547302`) from
      the LFS store; added TPS22810 (power/) and PUSB3AB6 (exi/) datasheets
      that were missing from the original set.
- [x] Deleted stale lowercase `power.kicad_sch` (the pre-rework draft from the
      first power-sheet commit; live sheet is `Power.kicad_sch`). It "kept
      coming back" because both paths were git-tracked: on a case-insensitive
      (Windows) checkout they are one file on disk, so deleting one path also
      deletes the other, and restoring the live sheet re-materialises both —
      the next commit resurrects the stale path. Removing the lowercase path
      from the git index (done from the case-sensitive devcontainer) is the
      permanent fix. **Never add two files differing only in case.**
- [x] Deleted `re-bba-rb.kicad_pcb.old.kicad_pcb` / `.old.kicad_pro` leftovers
      (recoverable from git history if ever needed).

## Verified correct — do not re-flag

TPS562201 (EN at 12 V legal, abs max 19 V; 0.768 V ref × 33k/10k = 3.30 V;
L/C per Table 7-2) · TPS2116 mode/ST logic (GC priority, USB fallback,
GC_ON polarity) · AP2112K ×2 · TPS22810 EN (never floats, R5 pull-up) ·
**FT2232H VPHY/VPLL on 3.3 V is correct per datasheet** (the VCORE→3V3
relabel at HEAD was a fix) · W5100S parallel-mode straps (MOD=0100, SCLK→GND,
pin32=A0/pin33=A1, INTn push-pull, internal pull-ups on CSn/RDn/WRn/DAT) ·
W5100S 1V2 loop + mandatory 1 MΩ crystal feedback · PUSB3AB6 pinout/footprint ·
USB-C CC/ESD wiring · iCE40 power/config/flash, CLK12 on G3, EXI_CLK on G6 ·
magjack transformer spec (1:1, 350 µH) · PCB vs JLCPCB capability floor
(rules in `re-bba-rb.kicad_dru`, 0 DRC errors).