ShiboSoftwareDev/i-wan

README.md

# MSP-EXP430FR2433 compatible LaunchPad — tscircuit edition

This repository contains a four-layer tscircuit implementation of a TI
MSP-EXP430FR2433-style LaunchPad. It includes the MSP430FR2433 target, a
USB-protected MSP430F5528 eZ-FET-style debugger/UART section, removable
debug/power isolation links, BoosterPack headers, buttons, LEDs, a 32.768 kHz
crystal, external-power access, test points, and an optional supercapacitor.

## Important design differences

- This is an electrically compatible reimplementation, not a geometric clone
  of TI's PCB.
- TI's EnergyTrace switch-mode measurement supply is replaced with a protected
  TLV70033 3.3 V LDO. Programming, SBW debug, USB UART, and board power remain;
  EnergyTrace current measurement does not.
- PCB fabrication and component assembly do not require firmware. The blank
  MSP430F5528 must be programmed with compatible eZ-FET firmware through
  `J_DBG_PROG` after assembly and before the USB debugger/UART section can
  enumerate. The target MSP430FR2433 can then be programmed through SBW.
- `C_SUPERCAP` is DNP by default. Install all seven `J_ISO_*` shunts for normal
  LaunchPad operation.

## Manufacturing package

- Board: 54 mm × 86 mm, 1.6 mm FR-4 recommended
- Copper order: F.Cu / In1.Cu (GND plane) / In2.Cu (eZ-FET 3.3 V plane) / B.Cu
- Minimum routed trace: 0.10 mm
- Routed vias: 0.30 mm drill, 0.45 mm copper pad
- Solder mask, paste, and silkscreen: top and bottom only

The PCB fabrication upload is
`fabrication/msp-exp430fr2433-4layer-gerbers.zip`. It was generated directly
from the validated Circuit JSON with `circuit-json-to-gerber` 0.0.94 and
contains four copper files, top/bottom mask, paste and silkscreen, the outline,
one plated L1-L4 drill file, and one NPTH file. Inner copper contains the plated
annuli for every through via but no solder-mask geometry.

The custom local autorouter first applies coordinated `FanoutSolver` escapes to
the two QFNs. It also splits the merged eZ-FET 3.3 V tree into one solver-owned
branch per QFN supply pad and escapes those branches beyond the fine-pitch pad
field before global routing. The remaining connections are routed while only
the two outer copper layers are exposed to the global solver. The physical board
remains four-layer, so every generated layer transition is a full-stack L1-L4
plated through via. The result has 215 through vias and no blind or buried drill
spans. There are no authored route points, route hints, fixed paths, or manual
via coordinates.

This removes the former blind/buried-via blocker for a standard JLCPCB
four-layer order. The 0.30 mm drill, 0.45 mm pad, and 0.10 mm minimum trace are
represented explicitly; JLCPCB's upload review remains the final manufacturing
acceptance gate.

The assembly set now locks one reviewed manufacturer part number and one live
JLCPCB/LCSC C-number for all 61 fitted placements:

- `fabrication/jlcpcb-bom.csv` and `fabrication/jlcpcb-cpl.csv` use JLCPCB's
  standard upload columns and exclude the DNP supercapacitor.
- `fabrication/bom.csv` and `fabrication/pick-and-place.csv` retain engineering
  details and the DNP state.
- `fabrication/assembly-accessories.csv` lists seven C100114 removable shunts
  for the C492401 isolation headers and the optional hand-fitted Panasonic
  EEC-S0HD224H supercapacitor.

The previous C2977587 BoosterPack candidate was rejected because it is a 2x5
receptacle. J1/J2 now use the correct 1x10 female C2897373. The placement
coordinates use the same coordinate system as the native Gerbers. Stock was
checked when the parts were selected; JLCPCB's upload matcher remains the final
availability and rotation review before ordering.

JLCPCB programming is optional and occurs only after PCBA. For a programmed
order, supply the MSP430F5528 firmware image, its MPN, the `J_DBG_PROG` pinout,
and programming instructions through the Standard PCBA function-test option.
Otherwise order blank assembly and flash it locally with an external MSP-FET or
another working LaunchPad. TI publishes eZ-FET Lite source/binary packages and
the MSP Debug Stack firmware sources.

## Rebuilding

The release dependencies are pinned exactly:

- `tscircuit` 0.0.2311 (`@tscircuit/cli` 0.1.1910, core 0.0.1665)
- `circuit-json-to-gerber` 0.0.94
- `circuit-json-to-kicad` 0.0.173

```sh
bun install --frozen-lockfile
bun run typecheck
bun run build
bun run export:gerbers
bun run export:kicad
bun run export:assembly
```

The Gerber export script recreates `fabrication/gerbers` before each export so
obsolete drill spans cannot survive a reroute and leak into the ZIP. The direct
export is intentional: the latest top-level `tsci export` bundle still uses an
older converter than the directly pinned packages.

## Verification results

- TypeScript: pass
- Coordinated fanout/global autorouter: 151 routed traces, 0 jumpers
- Manual routing directives: none (`pcbPath`, `pcbRouteHints`,
  `pcbStraightLine`, and `<pcbtrace>` are all absent)
- Generated Circuit JSON: 0 PCB/source errors, 151 total PCB traces
- Vias: 215, all 0.30 mm drill / 0.45 mm pad and all L1-L4 through vias
- Netlist check: 0 errors, 0 warnings
- Placement check/DRC: 0 errors, 0 warnings
- `bunx tsci check shorts --mode gerber --layer all --pixels-per-mm 20`: no
  shorts detected
- Fabrication archive: 11 Gerbers, one plated `drill-L1-L4.drl`, and one NPTH
  drill file; no blind/buried drill files
- Assembly export: 61 fitted placements, each with one exact MPN and LCSC number

The KiCad export is an optional review artifact, not the fabrication source. The
current converter output triggers an `Array index out of range` crash in KiCad
CLI 10.0.4 when DRC is started, so it is not a release gate. The JLCPCB upload
archive is produced independently by `circuit-json-to-gerber` and passes the
all-layer Gerber shorts check.

## Remaining tscircuit limitations observed

1. The router's exact-geometry stage can report no errors while final Circuit
   JSON DRC still finds a small clearance violation. A global 0.155 mm
   via-to-pad solver margin was needed to satisfy the board's 0.10 mm DRC rule;
   Circuit JSON DRC—not router status alone—is the release gate.
2. `tsci build` still exits with status 0 when Circuit JSON contains PCB errors.
3. `tsci check shorts --mode pcb` is broken for the BREP ground pour on inner1.
   The isolated repro fails with `layerCanvas.getContext is not a function` at
   low resolution and appears to hang while rasterizing at normal resolution.
   Top, bottom, and inner2 pass, removing the pours makes all layers pass, and
   the project-bundled and live latest CDN checkers fail identically. Generate
   the repros with `scripts/make-check-shorts-repros.mjs`. Gerber mode checks
   the emitted copper on all four layers and passes.
4. `tsci export --format gerbers` in tscircuit 0.0.2311 uses the bundled Gerber
   converter. The project pins 0.0.94 directly to include the inner-layer plated
   copper fix. That 0.0.94 package still writes `0.0.93` in its Gerber metadata.
5. The `circuit-to-gerber` binary shipped by 0.0.94 cannot start because its
   `archiver` runtime dependency is missing. `scripts/export-latest-gerbers.mjs`
   uses the supported library API instead.
6. The latest top-level tscircuit build still rejects JLCPCB C11337's blank
   `fontStyle`. The explicit verified SOT-23-5 footprint and pin map keep the LDO
   electrically and geometrically defined, but the parts-engine enrichment
   warning remains.
7. Supplier enrichment reports footprint-IoU mismatches for 29 reviewed
   0402/0603/header placements because tscircuit's generic pads are not
   geometrically identical to EasyEDA's recommended pads. The physical package
   sizes and exact order codes are correct; these warnings do not change the
   explicit PCB geometry. C11337 also still triggers the blank-`fontStyle`
   parser bug.
8. The native assembly SVG has severe reference-text overlaps on this dense
   board. Use the BOM/PnP files and PCB render for manufacturing review.
9. The native four-layer autorouter uses blind and buried vias, and its public
   board/autorouter props do not offer a through-via-only switch. This project
   works around that limitation with the local fanout/global solver pipeline.
10. A prebuilt JSON file is recognized by `tsci check shorts` only when named
    `circuit.json` or `*.circuit.json`; an arbitrary `.json` name is evaluated
    as source and produces a cryptic React `got: array` error.
11. `FanoutSolver` plane termination could not escape the three 3.3 V pads of
    the 0.5 mm-pitch debugger QFN with the required 0.45/0.30 mm through via;
    its best assignment routed 0/3 connections. Boundary fanout followed by
    the global solver succeeds without authored vias or route points.
12. The maximum-decoupling-length checker measures each entire ground MST branch
    and does not stop at the nearby connection to an internal ground plane. It
    therefore reports two 15.52 mm warnings for `C_DBG_VUSB` and `C_DBG_V18`,
    although their shared through via to In1.GND is about 1.5 mm away.
13. The `circuit-json-to-kicad` 0.0.173 file generated from the current poured
    inner layers crashes KiCad CLI 10.0.4 during DRC with a Swift array-index
    failure. The independently generated Gerber/Excellon package is unaffected.

The board is electrically routed with ordinary through vias, the source,
netlist, placement, and Circuit JSON error gates pass, and the Gerber all-layer
shorts check passes. The two maximum-trace-length warnings are the ground-plane
MST false positives described above. Review JLCPCB's BOM/CPL rotations and live
stock resolution before releasing the order.