0hmX/esp32-s3-usb-webcam-ov2640

ROUTING_EXPERIMENTS.md

# Routing Experiments Ledger

This is the canonical routing decision record. Detailed iteration logs remain
in each isolated worktree's `EXPERIMENT_RESULT.md`; this file records final,
auditable results and the selected integration only.

## Baseline and acceptance

- Canonical baseline HEAD: `6bab2c255e4ac6f638ecb887668e20656c024d7f`
- Original dirty-source snapshot:
  `bce6e7bceaaa5b12f7d17f60a5ced147129bea09209f220152df3975670fd437`
- Required gates: Bun typecheck/tests; clean netlist, schematic placement, and
  PCB placement; full routed build with zero Circuit JSON error/unrouted
  elements; zero shorts; top-only assembly; preserved 68 x 45 mm four-layer
  mechanics, four mounting holes, five keepouts, FPC interface, USB path,
  camera GPIO remap, and fabrication-valid via geometry.

Metrics below are `traces / vias / errors / unrouted / shorts` for each best or
most informative full-board candidate.

## Final experiment results

| ID | Commit | Approach and measured result | Decision |
| --- | --- | --- | --- |
| EXP-A | Baseline-only worktree at `6bab2c255e4ac6f638ecb887668e20656c024d7f` | Corrected phase ordering but retained nested ownership; best full candidate still had 18 unrouted endpoints and local shorts. | Rejected; motivated manual fanout. |
| EXP-B | `b075f35ed917f4df6e495afe8ea8654823038c79` | Deterministic 16-signal plus five-rail FPC fanout and phased board routing. B7: `149 / 147 / 1 / 0 / 0`; sole error was a 0.45/0.20 mm ESP_EN via overlapping the conservative RF keepout by about 0.021 mm. | Accepted as the stable topology/baseline for E–J. |
| EXP-C | `49432db63a22a632dc628c005965ba7e8d3b0a19` | Router matrix. Best C7 flat/manual-USB candidate: `128 / 195 / 5 / 0 / 0`; five camera via geometry errors remained. | Rejected. |
| EXP-D | `34dba47824841c140f54127c9d76b4e2df764606` | Proved automatic plane antipads with a clean fixture; demonstrated that the prior fault was 0.55 mm signal/GND via overlap. Full board: `128 / 159 / 7 / 0 / 1`. | Full route rejected; antipad/via-spacing evidence retained. |
| EXP-E | `f434114c795a20a4a6cf98c0220cd4f4f8c7a9d7` | Global 0.425/0.400/0.405 mm router-via variants each destabilized the general solve (`21 / 16 / 134 / 133 / 0`). | Rejected; global via changes are not route-stable. |
| EXP-F | `47b509d558b60c6782cea46c074c35a0ef944b13` | Tested EN hints, a local obstacle, and a manual transition. Hints were ignored or destabilized routing; manual transition reached `152 / 166 / 12 / 0 / 2`. | Rejected; restored B7. |
| EXP-G | `b6282d816ba7c414d0352cb277bc172178edb775` | Nudged U1 down by 0.050/0.025/0.021 mm. The smallest nudge cleared EN but globally rerouted to `149 / 161 / 4 / 0 / 0`. | Rejected; worse than B7. |
| EXP-H | `adb6920e3cc75edb97ec7dda4ca366bdfad58060` | Wrapped the normal general solver and moved only ESP_EN's colliding wire/via/wire transition by `(+0.400, -0.050)` mm. Standard 0.45/0.20 mm via; `149 / 147 / 0 / 0 / 0`; 148/149 trace objects unchanged. | **Winner.** Clean without extra-cost geometry or weakened keepout/DRC. |
| EXP-I | `ef0d3434e5b357432a7531ee69fe82fd08b775f0` | Changed only the semantic ESP_EN via OD to 0.39 mm while preserving all route geometry: `149 / 147 / 0 / 0 / 0`. | Clean fallback, but JLCPCB classifies the 0.39/0.20 mm via as an extra-cost small-via option. |
| EXP-J | `0c47c0ceb771ea376ffc1a1325368ac98a019e43` | Audited the RF keepout against Espressif sources. B7 is overconservative, but source-backed smaller keepouts globally rerouted to either `149 / 164 / 7 / 0 / 1` or an incomplete `21 / 16 / 134 / 133 / n/a`. | No-go; preserve the conservative keepout and fix only EN routing. |

## Selection rationale

EXP-H is selected over EXP-I because both are completely connected and clean,
but H retains the standard 0.45/0.20 mm via and changes only one ESP_EN trace.
EXP-I is retained as a technically clean fallback if exact B7 coordinates are
preferred and the extra-cost 0.39/0.20 mm via option is acceptable.

The EXP-J RF audit remains an important product caveat: the keepout is valid
and conservative, but the module antenna still sits over base-board substrate
instead of overhanging the board edge as Espressif recommends. Enclosure
clearance plus physical throughput/range testing remain mandatory.

## Canonical integration validation

Integrated from EXP-H into the dirty canonical worktree without cherry-picking
or overwriting unrelated configuration/history. Winning board, phase,
postprocessor, package-test, and focused-test files match EXP-H byte-for-byte;
the related README fanout description was updated from the obsolete nested
breakout to the manual-fanout architecture.

- Fresh full debug build: 12 camera-bus routes, 6 camera-control routes, and
  110 general routes; final `149 / 147 / 0 / 0 / 0`.
- `bun run typecheck`: pass. `bun test`: 5 pass / 0 fail.
- `tsci check netlist`: 0 errors / 0 warnings.
- `tsci check schematic-placement`: pass.
- Pre/post build `tsci check placement`: 0 errors / 0 warnings.
- `tsci check shorts dist/index/circuit.json`: no shorts.
- All 75 PCB components and all 16 capacitors are top-side; capacitor rotations
  are explicit. Board is 68 x 45 mm / four layers with four 2.7 mm holes and
  five keepouts.
- All 147 vias are valid: OD 0.45–0.55 mm, hole 0.20–0.25 mm, minimum radial
  annular ring 0.125 mm.
- Canonical Circuit JSON is identical to EXP-H except for the expected
  `source_project_metadata.source_filesystem_md5_hash`, which reflects the
  different worktree file set. Every trace, via, placement, pour, and other
  circuit element is identical.
- Fresh artifacts (2026-08-28 IST): `dist/index/circuit.json`,
  `dist/index/pcb.png`, and `dist/autorouter-debug/` including all three SRJ
  phase inputs/outputs and cumulative route PNGs.

Non-actionable CLI warnings remain for bounding-box overlaps among four DNP
camera rail fanout testpoints, missing courtyards on DNP/test-point primitives,
and incomplete optional pin classification metadata. They do not emit Circuit
JSON errors or shorts. No publish, fabrication order, or external push has been
performed.