mohan-bee/drone

DEVELOPER_NOTES.md

# Developer Notes

## Scope

This project recreates the schematic, board outline, internal cutouts, and
component placement from `ESP32 drone.kicad_sch` and
`ESP32 drone.kicad_pcb` in tscircuit.

The KiCad board uses a complex 100 mm × 100 mm drone-frame outline. All 74
referenced electrical footprints have been mapped to their KiCad positions and
rotations. Placement values are generated in `board/KicadPlacement.ts`.

## Current fidelity

- 74 of 74 referenced electrical footprints have `pcbX`, `pcbY`,
  `pcbRotation`, and layer data derived directly from KiCad.
- All referenced electrical components are on the top layer in the source PCB.
- Pad-direction auditing found and corrected the different zero-angle conventions
  used by IC1, SW1, U7, J8, J9, and T1–T4.
- J8 and J9 receive a 6.35 mm origin correction so pin 1, rather than the
  geometric center of the six-pin row, lands on the KiCad footprint origin.
- U2 retains the tscircuit MOSFET component, but its three SOT-23 pads now match
  the KiCad AO3401 pad coordinates and sizes exactly.
- The board outline contains 224 lines and 170 arcs, reconstructed as one outer
  contour and ten polygon cutouts.
- The outline is centered without scaling. Its measured bounds are
  100.00005 mm × 100.00005 mm.
- Schematic and full-board netlist checks pass with no errors or warnings.

## Remaining fidelity limits

### Footprint origin versus component center

KiCad stores placement at the footprint origin. tscircuit's generated
`pcb_component.center` is based on the resulting footprint bounds. These values
are identical for 68 components, but six non-centered connector footprints show
an offset between their KiCad origin and reported tscircuit center:

| Reference | Center offset from requested placement |
| --- | --- |
| J1 | `(0.000000, +0.424999) mm` |
| J3 | `(-0.874998, 0.000000) mm` |
| J2 | `(+0.616900, -0.741900) mm` |
| J5 | `(+0.616900, +0.741900) mm` |
| J6 | `(-0.616900, +0.741900) mm` |
| J4 | `(-0.616900, -0.741900) mm` |

The requested `pcbX` and `pcbY` values are exact, but exact pad-level alignment
cannot be guaranteed when the tscircuit/JLCPCB footprint uses a different local
origin or geometry from the KiCad footprint.

### Mechanical footprints not recreated

The KiCad PCB contains 56 anonymous `REF**` mechanical footprints and one
bottom-layer `G***` graphic footprint. They are not electrical placements and
were intentionally omitted. Some anonymous footprints appear to provide frame
holes or mechanical details. They should be imported separately if the final
manufacturing output must include their pads or drills in addition to the
Edge.Cuts geometry.

### Placement DRC

All actionable placement violations have been cleared by moving components into
nearby open regions while preserving the approved PCB rotations. Standalone
placement checking now reports zero errors.

One connector-accessibility warning remains. The checker prefers the connector
to face the opposite direction, but changing that rotation would undo the
explicitly approved connector orientation. It is not an overlap, board-edge, or
electrical error.

## Where most time was spent

1. Reconstructing connected Edge.Cuts loops from hundreds of unordered KiCad
   line and arc records.
2. Tessellating arcs because board outlines and polygon cutouts accept points,
   but not native circular arcs.
3. Determining the coordinate transform shared by Edge.Cuts and footprint
   placements.
4. Auditing footprint-origin offsets after placement. A correct `pcbX`/`pcbY`
   does not necessarily mean that two footprints with different local origins
   overlap geometrically.
5. Comparing numbered pad vectors to detect component-specific zero-angle
   differences hidden by apparently correct `pcbRotation` values.
6. Working around parser incompatibility. The installed `kicadts` parser stops
   on a valid KiCad pad primitive with `gr_circle (fill solid)`, so a dedicated
   balanced S-expression extractor was required.

The complex outline also increases build and preview time because 170 arcs are
represented by thousands of polygon points.

## Improvements that would help tscircuit developers

### Native KiCad board-geometry import

An API or CLI command that imports `Edge.Cuts`, preserves closed-loop topology,
and emits a board outline plus cutouts would remove a large custom conversion
step. Native support for line, arc, circle, rectangle, and polygon primitives is
important.

### Arc-aware outlines and cutouts

Allow board outlines and polygon cutouts to contain line and arc segments rather
than only sampled points. This would retain exact radii, substantially reduce
JSON size, and speed up rendering and DRC.

### Explicit footprint-origin placement

Add a placement mode such as `pcbAnchor="footprint-origin"`, or expose
`pcbOriginX`/`pcbOriginY`. The resulting origin should be preserved in circuit
JSON independently of the calculated bounding-box center. This is necessary for
lossless KiCad placement transfer.

### Preserve origin metadata in imported parts

JLCPCB/EasyEDA imports should expose their source origin and a predictable
anchor. A diagnostic showing the difference between requested placement,
footprint origin, and calculated component center would make cross-CAD alignment
much easier.

### KiCad parser compatibility

The parser should accept current KiCad syntax such as pad-primitive
`gr_circle (fill solid)`. A tolerant mode that retains unknown expressions would
also be useful for geometry and placement extraction.

### Selective DRC and faster mechanical previews

A board-geometry-only preview mode and granular DRC exclusions would help when
the active task is only outline or placement transfer. It should be possible to
skip trace, pin-specification, supplier-footprint, and placement checks without
generating hundreds of unrelated messages.

### Placement comparison command

A command that compares a KiCad PCB against circuit JSON by reference and
reports position, rotation, layer, footprint-origin, and pad-coordinate deltas
would turn this manual verification into a reproducible check.

The project now includes `work/compare-pad-orientations.mjs` as a local proof
of concept. It reports pad-vector angle error, origin translation, and RMS pad
geometry mismatch for every component with comparable numbered pads.

## Regeneration

The generated data can be refreshed with:

```sh
node work/extract-board-outline.mjs "/path/to/board.kicad_pcb" --write board/DroneFrameGeometry.ts
node work/extract-kicad-placement.mjs "/path/to/board.kicad_pcb" --write board/KicadPlacement.ts
```

Both scripts use the same KiCad-to-tscircuit coordinate transform and do not
scale the source geometry.