seveibar/adm6-breakout

README.md

# ADM6-60 to RP2040 autorouter stress breakout

This tscircuit project exercises the exact 240-contact land pattern of the
Samtec `ADM6-60-03.5-L-4-0-A-TR` and includes an RP2040 integration fixture.
It includes these fixtures:

The default entrypoint is the minimal two-part connector-fanout board,
`rp2040-connector-routed.circuit.tsx`. All current fixtures are capped at
`1x` effort. Previously recorded higher-effort diagnostic artifacts are
retained as historical evidence, not as the current build configuration.

- `adm6-fanout.circuit.tsx` is the deterministic footprint baseline. It asks
  the fanout stage to escape all 240 contacts and then deliberately bounds the
  slower follow-up stage at 20 seconds.
- `index.circuit.tsx` is the full RP2040 stress case. It exposes all contacts
  on four 60-pad, 1.27 mm breakout rows and connects selected contacts to a
  complete RP2040 support circuit.
- `adm6-no-fanout.circuit.tsx` is the direct comparison: the same exact
  connector and 240 destinations routed by `auto-local` without a `<fanout>`.
- `rp2040-connector-unrouted.circuit.tsx` is a minimal two-part view containing
  only the RP2040 and ADM6, with routing disabled. It uses the same 30 random
  connector contacts and four-layer board as the routed fixture.
- `rp2040-connector-routed.circuit.tsx` routes the same two-part placement and
  30 GPIO connections using a fanout region around only the ADM6. Effort is fixed
  at `1x`; there are no manual breakout points or extra endpoint pads.

## Current minimal-board result

The **four-layer, 30-connection fixture completes at `1x` with no reported
routing/DRC errors**. The connector-only fanout completed in 0.65 seconds
with all 30 escape traces; the follow-up router completed in 8.3 seconds.
The full SVG is `dist/rp2040-connector-routed/pcb.svg`. The final circuit
contains 2 components, 297 pads, 60 trace records, and 74 vias.

`pin-mapping.ts` uses a seeded Fisher-Yates shuffle of all 240 ADM6 contacts
and selects the first 30 without replacement. The fixed seed `0x2040060`
makes reruns reproducible. The selection spans A: 9, B: 7, C: 12, D: 2
contacts, mapped in shuffled order to RP2040 GPIO0..GPIO29. The seed was not
rerolled between routing attempts. Full pin assignments are included in
`dist/rp2040-connector-routed/verification.json`.

Current minimal-board settings:

- 48 × 28 mm board, four copper layers: top, inner1, inner2, bottom;
- one 46 × 10 mm fanout surrounding only J1;
- row A/B buses escape upward; row C/D buses escape downward;
- 0.10 mm traces, 0.08 mm local clearances;
- 0.20 mm drilled through vias with 0.40 mm pads;
- board and fanout autorouter effort both explicitly `1x`.

With 0.45 mm via pads, the row-directed fanout escaped only 11 of 30
contacts. Reducing the pad diameter to 0.40 mm while keeping the drill and
clearances unchanged allowed all selected inner-row contacts to escape.
No blind/buried-via option is enabled.

`npm run verify:simple` checks the layer count, 30 unique contacts across
all rows, exact GPIO mappings and routed endpoints, two components, fanout
completion, and all reported errors. It writes `verification.json` and
exits with status 1 if DRC errors are reported. The two-part circuit still
has expected power/ground and component-metadata warnings: it is a routing
test, not an operational RP2040 board or a fabrication release.
Automatic boundary bookkeeping in circuit JSON is generated by `<fanout>`;
no `<breakoutpoint>` elements are authored.

The preceding 57-pin, eight-layer result with nine DRC error reports is
preserved separately in `dist/rp2040-connector-57pin-8layer/`.

## Full integration wiring (`index.circuit.tsx`)

- `A01..A16` -> RP2040 `GPIO0..GPIO15`
- `B01..B10` -> RP2040 `GPIO16..GPIO25`
- `B11..B14` -> RP2040 `GPIO26_ADC0..GPIO29_ADC3`
- `A57` -> 3.3 V, `A58` -> GND, `A59` -> SWD, `A60` -> SWCLK
- `B57` -> RUN, `B58` -> USB D-, `B59` -> USB D+, `B60` -> GND
- All remaining contacts remain one-to-one breakout pads.

The RP2040 support circuit includes a W25Q16JV QSPI flash, 12 MHz crystal,
load capacitors, decoupling, RUN pull-up, SWD header, and external regulated
3.3 V input. The board deliberately omits a USB receptacle and regulator;
apply regulated 3.3 V at `J_PWR`.

## Historical 240-contact baseline result

`npm run build:baseline` runs the bounded baseline, checks the saved stage artifact,
and renders it. The current result is:

- 240 dense fanout traces
- 240 unique ADM6 pads escaped
- 240 vias
- top, bottom, and inner4 used by the fanout solver

The first dense stage succeeds. The follow-up autorouter receives all 240
traces but does not converge inside the 20-second test budget; that timeout is
intentional and is kept as the bug/performance reproducer. The wrapper script
only exits successfully after proving the first-stage artifact contains all
240 unique connector escapes.

### Direct routing without `<fanout>`

The no-fanout comparison does not complete under the tested settings. With
the same 8-layer stackup, 0.10 mm traces, 0.08 mm clearance, 240 connections,
and `10x` effort, the normal `auto-local` router timed out after 300.6 seconds
in phase 1. It reached `exactGeometryDrcForceImproveSolver`, but emitted no
completed PCB trace set. In this fixture, `<fanout>` is therefore necessary
for a deterministic dense escape result.

The saved comparison artifacts are in `dist/adm6-no-fanout-debug/`. Run
`npm run verify:no-fanout` to inspect and validate the recorded result. To
rerun the five-minute comparison itself, use `npm run build:no-fanout`.
That rerun now uses the user-requested `1x` cap, rather than the historical
`10x` setting described above.

Generated evidence:

- `dist/adm6-fanout/fanout-stage.png`
- `dist/adm6-fanout/fanout-stage.svg`
- `dist/adm6-fanout/fanout-stage.circuit.json`
- `dist/autorouter-debug/phase-1.previous-output.traces.json`
- `dist/autorouter-debug/phase-1.timeout.json`

## Historical/full-integration autorouting setup

- 8-layer board
- ADM6 fanout on top, bottom, and inner1..inner4
- inner5 GND plane and inner6 3.3 V plane
- 0.10 mm nominal traces, 0.08 mm local clearance
- 0.20/0.45 mm via hole/pad constraints
- separate fanout regions for the ADM6 and RP2040, followed by local board
  autorouting in the full integration circuit

The connector was imported from the exact JLC/EasyEDA record `C25097299`.
Its generated land pattern uses 0.356 mm circular pads on 0.635 mm pitch and
0.95 mm non-plated alignment holes, matching the key dimensions in Samtec's
recommended PCB layout. The imported connector file is intentionally checked
into `imports/` so the stress case is reproducible.

## Run it

Cloud CI invokes `npm run build:ci`, which explicitly builds only
`rp2040-connector-routed.circuit.tsx`: the 30-pin, four-layer, `1x` fixture.
The 30-minute worker timeout (`build.workerTimeoutMs: 1800000`) remains as a
safety limit, but the historical stress fixtures are no longer part of CI.
`index.circuit.tsx` is a compatibility entrypoint for the same published
fixture; the former full-integration source is retained as
`historical-full-integration.tsx` for local, manual experimentation only.
Local scripts retain their separate per-autorouting-phase time limits.

```sh
npm install
npm run typecheck
npm run build
npm run verify
```

To run the complete RP2040 integration with a ten-minute router budget:

```sh
npm run build:integration
```

For full per-phase integration debug artifacts, use `npm run build:debug`.
The integration fixture is intentionally difficult and may time out in the
follow-up routing phase; that behavior is part of the test case, not a claim
that the board is fabrication-ready.

To render the unrouted placement snapshot without invoking either autorouter:

```sh
npm run build:unrouted
```

To route that same minimal two-part design and generate its PCB SVG/PNG:

```sh
npm run build:simple
npm run verify:simple
```

Its output directory is `dist/rp2040-connector-routed/`. The 30-pin mapping
is an autorouter test fixture, not a complete operational RP2040 circuit.
The board and its connector fanout both use `1x` effort. The ten-minute
per-phase wall-clock limit is a timeout, not an effort multiplier. Traces
and the row buses are declared outside the fanout wrapper; the wrapper contains
only the connector. Boundary transitions are automatic, with no explicit
`<breakoutpoint>` elements and no extra physical endpoint pads.

This is an autorouter evaluation fixture, not a released production design.
Confirm stackup, via technology, impedance, return paths, stencil design, and
Samtec's latest footprint drawing before fabrication.

## Primary references

- DigiKey part: https://www.digikey.com/en/products/detail/samtec-inc/ADM6-60-03-5-L-4-0-A-TR/27485956
- Samtec product page: https://www.samtec.com/products/adm6-60-03.5-l-4-0-tr
- Samtec recommended footprint: https://suddendocs.samtec.com/prints/adm6-xxx-xx.x-xxx-x-x-x-footprint.pdf
- RP2040 hardware design guide: https://datasheets.raspberrypi.com/rp2040/hardware-design-with-rp2040.pdf