README.md
# AM3352 development board
A compact **70 × 60 mm, eight-layer, 1.2 mm thick** tscircuit design around **AM3352BZCZ100**, with 128 MiB DDR3, microSD boot storage, USB device, UART, JTAG, SPI/I²C expansion, and selectable SYSBOOT straps. The PCB area is 47.5% smaller than the original 100 × 80 mm draft.
All 185 components are placed and all 138 electrical nets are physically connected. The native build reports two existing crystal-net maximum-length errors (RTC_XTALIN and XTALOUT), and the independent audit reports zero incomplete nets and zero clearance violations at 0.10 mm nominal clearance (3 µm numerical tolerance). TypeScript and tooling regression checks pass. The reports in `design/validation.json` and `design/copper-audit.json` identify the validated circuit JSON. This is an engineering design, not a fabrication release or a verified bootable product. **All 46 synchronous DDR nets pass planar length matching; total path/delay skew remains unconfirmed because the signals use different layer depths.** Route lengths remain near the 18.50 mm byte-0, 12.10 mm byte-1, and 35.02 mm address/control targets after dogbone cleanup; the measured byte skews are 0.050147 mm and 0.050016 mm. CK and both DQS pairs use inner2 with two endpoint vias each. The compiled measurements pass byte/pair skew and conservative placement-derived nominal-length limits; see [DDR-SKEW.md](DDR-SKEW.md). `npm run verify:ddr` enforces all of those measured limits. These are PCB centerline lengths; layer-dependent propagation, via delay, coupling, and impedance require the fabrication stackup and SI review.
## Open and build
```sh
npm install
npm run dev
npm run typecheck
npm run build
python3 -m pip install -r requirements.txt
npm run audit:copper
npm run verify
npm run verify:ddr
```
`index.circuit.tsx` is the entry point. `npm run build` keeps routing DRC enabled. `npm run build:checkpoint` permits incomplete routing while developing a phase. For placement-only work, use `npx tsci build index.circuit.tsx --routing-disabled --disable-parts-engine --pcb-svgs`.
The board keeps **`routeRemaining={false}`**. Every named net has an explicit phase assignment in `design/routing.ts`:
1. Oscillators and analog references.
2. DDR data, address, command, and clock.
3. USB, microSD, UART, SPI, and status LED.
4. Reset, debug, I²C, boot selection, and regulator switching nodes.
5. Supply rails.
6. Ground distribution.
The routing cleanup removes 1,746 saved route vertices, replacing staircase detours with longer straight/45° runs while preserving the matched DDR and USB lengths. Ground and supply angles are regularized where pad, via, and copper clearances allow. See `design/routing-cleanup-summary.json` for before/after geometry counts. Remaining DDR tuning bends supply the required matched length.
Saved copper is replayed through tscircuit’s custom router interface by `design/replay-router.ts`. The replay checks endpoint coordinates; moving a connected part requires regenerating its routing data. The complete board still runs ordinary tscircuit checks after replay. Schematic rendering is enabled. Eight named sheets cover processor supplies, DDR, interfaces, clocks/reset, the PMIC, boot straps, unused pins, and decoupling. The processor, RAM, and PMIC use schematic-only units referencing the same physical components; all 469 IC pins are represented. `design/schematic-plan.json` controls their manual layout. Render the individual SVG/PNG sheets with `npm run render:schematic` and check coverage and cable pinouts with `npm run verify:interfaces`.
## Layout and circuitry
- AM3352: all 324 balls mapped from TI SPRS717L, with 0.8 mm pitch and provisional 0.4 mm lands. Seventy-two bottom-side processor decouplers have individual positions and orientations selected for their associated power balls and nearby power/ground vias. The compiled mean power-pad-to-ball projected distance is 2.087 mm (previously 9.171 mm); the maximum is 4.220 mm (previously 18.32 mm).
- TPS65217C: external 5 V input, three buck converters with inductors and local capacitors placed beside the PMIC, RTC 1.8 V, main 1.8 V, 3.3 V, and analog supplies. The power-on MPU/core defaults are 1.1 V; 1 GHz operation requires appropriate software voltage/frequency setup.
- W631GG6MB-12: 128 MiB x16 DDR3, reference divider, ZQ/VTP resistors, and eighteen local bottom-side 100 nF decouplers, one assigned to each supply ball. Their mean projected pad-to-ball distance is 0.393 mm and maximum is 1.2 mm. Imported labels A1=VDDQ1, N7=A12, and P7=A1 were corrected. Ball names and signal aliases are separated so address A11 cannot alias the A1 supply ball.
- MicroSD, micro-USB B device/boot connector, UART, custom 14-pin JTAG, SPI/I²C GPIO header, reset, and PMIC push-button test point. Bottom-left locking JST-GH connectors provide six-pin SPI, four-pin I²C, and four-pin UART programming access. See [PROGRAMMING.md](PROGRAMMING.md) for pinouts, mating parts, power requirements, and bootloader prerequisites. All four USB shield mounting pads are explicitly grounded.
- 24 MHz and 32.768 kHz crystal circuits, sixteen 1.27 mm SYSBOOT selector headers, power LED, and four 3.2 mm mounting holes.
- Inner1 and inner6 are continuous ground reference planes, with clearances around other nets. Signal routing uses 0.10 mm track/space and 0.30/0.15 mm through vias; the PMIC thermal vias retain 0.40/0.20 mm geometry. Supply fills occupy separate regions of inner2 (DDR 1.5 V and analog 3.3 V), inner3 (core), inner4 (MPU), inner5 (1.8 V), and bottom (3.3 V), clipped around other copper. Explicit paths contained inside the pours make plane contacts visible to trace-based connectivity checks.
Build the interactive HTML viewer with `npm run build:site`; its entry page is `dist/index.html`. Serve `dist` over local HTTP to use the viewer.
## Routing toolchain
The source remains a tscircuit project. Freerouting was used for global copper routing, followed by local geometry-checked connections. The saved copper builds without Java or Freerouting. The routing development helpers use session scratch paths under `../../work`; regenerating the entire layout requires adapting those paths and supplying Freerouting 2.0.1 and the local maze-router executable (source in `scripts/maze.cpp`; Java driver in `scripts/RouteStable.java`). The build, audit, validation, measurement, preview, and via-manifest scripts run directly from this project.
- `scripts/export-router.py`: exports actual pad geometry, net assignments, and layer positions to DSN.
- `scripts/assign-ddr-escapes.py`: assigns BGA escape sites before routing; do not rerun on a finished layout without rerouting the affected nets.
- `scripts/resume-router.py`: merges a saved SES checkpoint into its DSN for additional routing passes.
- `scripts/import-router.py`: imports SES wires and actual via pad sizes into `design/routed-copper.json`.
- `scripts/plane-tree.py`: adds explicit paths wholly contained within generated ground and supply planes.
- `scripts/audit-copper.py`: independently checks physical pad/trace/via/pour connectivity and clearances, using Shapely.
- `scripts/check-ddr-skew.py`: validates compiled CPU-to-RAM centerline paths for both complete byte lanes, CK, address/control, and placement-derived nominal limits. `design/ddr-length-targets.json` records the tuning targets.
- `scripts/route-ddr-matched.py` and `scripts/route-ddr-multilayer.py`: development helpers that replace long DDR detours, reserve tuning space during routing, and finish congested address/control paths. They use the same scratch maze runtime as the other routing helpers.
- `scripts/measure-routing.mjs`: reports planar DDR/USB route lengths and compares relevant skew targets. This does not include via barrel delay or establish controlled impedance.
`npm install` applies the pinned dependency corrections in `scripts/patch-endpoint-inference.mjs` and `scripts/patch-via-connectivity.mjs`. The first prevents the checker from assigning a track endpoint to a pad on another net or copper layer merely because their XY positions overlap. The second joins separate track records through actual plated vias on their spanned layers. `npm run test:tooling` checks contacts, layer isolation, and net isolation; ordinary routing DRC remains enabled.
`design/timing-constraints.tsx` contains reference constraints for subsequent timing work; it is **not instantiated in the current board**. Do not interpret it as evidence of length matching.
Twenty-nine filled and copper-capped through vias are required at the locations listed in `design/filled-vias.csv` and `design/filled-vias.json`, including the PMIC thermal pad. Coordinates are in millimetres relative to the board center. The 0.15 mm through drills and 1.2 mm board thickness require fabricator stackup/process review. The manifest must accompany any later fabrication package.
The optimized capacitor coordinates are stored in `design/decoupling-placement.json`; `design/decoupling-validation.json` measures the actual compiled pad positions. Optimization retains signal escape copper and checks component courtyards and via clearances. These planar distances are placement metrics, not electrical loop-inductance or power-integrity signoff.
## Review before fabrication
Complete DDR/USB length matching, stackup and impedance selection, power-current and voltage-drop checks, regulator component ratings, and signal/power integrity review. Resolve the exact SYSBOOT shunt pattern for the selected ROM boot order and oscillator configuration. Finish PMIC no-battery application details, reset sequencing, unused-pin terminations, input protection, USB ESD protection, and VBUS sensing review.
Select actual crystal and passive MPNs and check their footprints, ESR, loading, capacitor derating, and inductor ratings. The crystal footprints currently reserve space and are provisional. Review analog/PLL filtering, imported footprint orientations, connector accessibility, complete ERC/DRC, and prepare bring-up firmware. The USB connector does not power the board in this revision.
## References
- [TI AM335x datasheet, SPRS717L](https://www.ti.com/lit/ds/symlink/am3352.pdf).
- [TI TPS65217 datasheet](https://www.ti.com/lit/ds/symlink/tps65217.pdf).
- [Winbond W631GG6MB A03 datasheet](https://media.digikey.com/pdf/Data%20Sheets/Winbond%20PDFs/W631GG6MB_A03.pdf).
- [TI AM335x schematic checklist](https://e2e.ti.com/cfs-file/__key/communityserver-discussions-components-files/791/sprabn2.pdf).
## Pad escape cleanup
Removed 32 unused vias that contacted copper on only one layer (429 → 397 vias). Replaced 82 short CPU/RAM pad escapes with direct 45° dogbones and adjusted their continuation traces. Thirty-four other candidate escapes remain unchanged because the cleanup could not satisfy its clearance and length-preservation constraints. Power/ground plane connections and thermal vias remain intact.
The rebuilt copper passes the independent physical audit: 138 connected nets, zero incomplete nets, zero clearance violations. All 11 planar DDR checks pass. `npm run verify:pad-escapes` verifies every removed via and direct dogbone against the emitted Circuit JSON. The detailed change record is `design/pad-escape-cleanup.json`.
The project now uses published core 0.0.1936, which includes the named-net bus fix, instead of the temporary vendored package.
