ESP32_Serial_Swiss_Army_Knife/hardware/PCB/pcb-draft-notes.md

# Compact two-layer PCB — A1 draft

Open **`serial-carrier.kicad_pcb`** in KiCad 10. The routed board belongs to the
existing `serial-carrier.kicad_pro` / `.kicad_sch` project. **Not for fabrication.**
No Gerbers, production drills or manufacturing archive were generated.

## Size and placement

- **Carrier bounding dimensions: 82 × 80 mm**, within the requested 100 × 100 mm.
- **Two copper layers**, F.Cu and B.Cu. All components mount on the front.
- Proposed **1.6 mm** carrier thickness; fabrication stackup/process not selected.
- Stepped outline: a **36 × 19 mm top-left antenna cutaway** fits within a simple
  rectangular/square case. The lower edge is now straight, with ESP32 USB toward
  the bottom and RS-232 toward the top. U1 moved down by 19 mm; its exact USB/body
  registration remains provisional pending the user's measured ESP32 geometry.
- Module and mating-plug overhangs are not included in the carrier dimensions.
  The final complete assembly/enclosure envelope still needs measurement.

Coordinates in the following table are local millimetres from the carrier's
upper-left corner, X right/Y down, viewed from the component side. In the KiCad
file add (100, 100) mm to obtain absolute board coordinates. All footprints are
unrotated; their origins are defined in the footprint notes, not necessarily
component body corners.

| Reference | Local origin (X, Y) | Placement |
|---|---|---|
| U1 | (8, 23) | ESP32 left header pin 1; antenna toward top-left cutaway, USB toward bottom edge |
| U2 | (43, 26.670) | MAX3243 header pin 1; bare module PCB front exactly flush with carrier top edge |
| DS1 | (43, 36) | OLED module upper-left PCB corner; display faces up |
| R1 / R2 / R3 | (43 / 54 / 65, 34) | Axial pull-ups in the gap between RS-232 and OLED |
| SW1 / SW2 / SW3 | (43 / 55 / 67, 68) | Back, select, next below display; switch pad 1 origins |
| H1 | (3.5, 22.5) | Proposed case mounting hole below antenna notch |
| H2 | (3.5, 75) | Proposed case mounting hole near bottom-left edge |
| H3 | (78, 4) | Proposed case mounting hole |
| H4 | (78, 76) | Proposed case mounting hole |

Outline vertices: (36,0), (82,0), (82,80), (0,80), (0,19), (36,19), closed.
The previous A0 board is retained in `validation/pcb-a0-before-reposition.kicad_pcb`.
The board area is **58.76 cm²**; its bounding rectangle is 65.6 cm².

H1–H4 are proposed **Ø3.2 mm NPTH M3 clearance holes**, not a previously agreed
case specification. They are marked board-only and excluded from the electrical
BOM. The OLED and RS-232 module mounting holes are additional, separate holes.
Screw heads, spacers, heat-set inserts, tool access and underside lead clearance
must be checked against the final case and assembly heights. No insert dimensions
or module stand-off heights are assumed.

## Routing and electrical status

The PCB contains actual copper, not just ratsnest placement:

- All **38 required physical-pad spanning connections** across **17 connected
  nets** routed, including both duplicated pads of each switch contact.
- **565 segments**, signal width **0.25 mm**, 3.3 V and GND width **0.50 mm**.
- **22 through vias**, **0.70 mm copper / 0.30 mm drill**.
- **No copper pours**; ground is explicitly routed. This is an initial routing
  solution, not a reviewed return-current/EMI or power-integrity design.
- Proposed minimum different-net clearance **0.25 mm** and copper-edge clearance
  **0.50 mm**. These are selected draft design rules, not fabrication qualification.
- Project netclasses align interactive routing defaults with the draft: Default
  uses 0.25 mm tracks / 0.25 mm clearance, while Power matches `/+3V3` and `/GND`
  with 0.50 mm tracks. Both use 0.70 / 0.30 mm vias.
- Schematic pad-net assignments, component values and UUID linkage are retained.
  U1's intentionally unused GPIO/USB/UART0/5 V header pads remain unused.

The bounded draft router prioritizes connectivity and conservative geometric
clearance, not optimal trace topology. Do not treat DRC passage as evidence of
current-carrying capacity, supply stability, I²C signal quality or EMC compliance.

## Explicit provisional mechanical choices

### ESP32 and RF

A two-layer **no-tracks/no-vias/no-pads/no-zone-fill rule area** reserves local
X=10…31 mm, Y=19…32 mm beneath the antenna-side end of U1, adjacent to the notch. This is a deliberate carrier design
allocation, **not a measured antenna envelope or a manufacturer RF keepout**.
The module itself may span the rule area; footprint placement is not forbidden.
No carrier copper enters the reserve, but copper runs close to its boundary.

U1's exact PCB/antenna/USB offsets are still unmeasured. The intended antenna
overhang and USB access must be checked with the actual board and a printed
placement template. Move U1, change the edge or enlarge the reserve if required.
Missing RF clearance cannot be signed off from the current footprint alone.

### RS-232

U2 uses the new **`Carrier:MAX3243_Reference_Provisional`** footprint **on the PCB
only**. Its bare-module outline/header/holes are adapted from published female
5988 CAD for the intended male 6253 module. The user explicitly confirms identical
male/female external dimensions. The linked Adafruit STEP has now been measured
with OpenCascade; its nominal metal geometry is used on that basis. Male header
mapping, actual fit, tolerances and the mounting stack still need qualification.
See `rs232-footprint-notes.md` and `db9-mechanical-notes.md` for evidence/licenses.

The module's **bare PCB front is flush with carrier Y=0**, as requested. The
connector has distinct front planes, not one universal case-wall datum:

| Feature | Position relative to carrier top edge | Meaning |
|---|---:|---|
| Flange front / shell root | 1.930 mm inside | Behind the PCB edge |
| Breakout PCB front | 0 | Flush with the carrier edge |
| Hex screw-lock mouth faces | 2.870 mm outside | Front cable-retention hole mouths |
| Shell nose | 3.870 mm outside | Foremost modeled shell surface |

The front screw-lock axes are **25.000 mm apart**, with centres **6.277620 mm
above the module PCB top**. They are not the two 24.130 mm-spaced PCB mounting
holes. The source models Ø3.000 mm bores but **no threads**; this does not establish
M3 or 4-40 hardware. The main metal flange is 30.800 × 12.550 × 0.400 mm; the
shell envelope including its root/lip is 16.878 × 9.100 × 5.800 mm.

`add_db9_envelope.py` places the measured metal bounding projections and screw-lock
axes on **Dwgs.User**, relative to U2. They are not silkscreen, a courtyard or a
case cutout. Run the helper after moving U2; it preserves copper and project
settings. The original STEP and its extraction/validation scripts are retained.

**Case-wall positioning remains a design decision:** PCB-edge alignment does not
put the flange or screw-lock mouths at that same plane. For example, making the
hex mouths flush with the case exterior would place that exterior 2.870 mm beyond
the carrier edge. No wall thickness, cable-backshell clearance or sealing scheme
has been assumed. The model's anchor legs extend **2.230 mm below the module
underside**; select a stand-off/header stack or clearance solution before assembly.

The schematic footprint remains intentionally blank, preserving its caution
and avoiding edits to the schematic that was open in KiCad. Consequently there
is **one known schematic-parity warning**: U2 footprint differs from the empty
schematic assignment. This is not excluded/suppressed, and is not a net mismatch.
Once the male footprint is qualified, explicitly assign it in the schematic
before relying on Update PCB from Schematic to manage U2's footprint.

### OLED and controls

OLED geometry, including its display boundary, is the user-fit-verified geometry.
The module schematic/library files are unchanged. The new overall placement still
needs an assembly fit check: adjacent resistor bodies, module underside parts,
header/socket bodies, button actuation and finger/plunger clearance are not
represented by complete assembly courtyards. In particular the axial resistors
are tightly packed between the module outlines; confirm clearance and height.

## Device outlines on front silkscreen

The PCB now has **0.12 mm front-silkscreen outlines** for the OLED PCB and the
published RS-232 reference module, plus a dashed OLED display boundary. The
RS-232's visible rounded corners retain true arcs. Small gaps clear pad/mask
openings, vias and adjacent resistor markings; the original full F.Fab geometry
remains unchanged.

U1 instead has **header-row guides**, labelled `HEADER GUIDES`: guide edges are
1.20 mm outside the outer pin centres. These are graphic alignment aids, **not
claimed socket-body dimensions or an inferred ESP32 PCB outline**. The actual
U1 body/antenna/USB outline still requires measured offsets. Existing button and
resistor silkscreen remains unchanged.

These are board-local drawings, not edits to the footprint libraries. If the
module placement or routing changes, close PCB Editor and refresh them with:

```sh
/usr/bin/python3 -B hardware/PCB/add_device_silkscreen.py
```

The script requires pcbnew and Shapely, replaces only its own generated graphics,
and refuses an open PCB or concurrent board change. It leaves project settings,
copper, pads and source F.Fab outlines unchanged. Run it **after** placement or
routing regeneration; moving a footprint does not move these board-local drawings.
It currently supports the draft's unrotated module placements.

The original A0 silkscreen-only change left its routing unchanged. A1 deliberately
repositions U1/U2 and reroutes all connections, then refreshes these outlines.
Silkscreen is clipped away from the new flush U2 front board edge. Physical DRC
remains **0 violations**, **0 unconnected**, with the same U2 footprint-parity
warning. PDF and both previews have been refreshed.

## Review outputs

- `validation/pcb-draft.svg` / `pcb-draft.png`: combined copper/outline/fab review.
- `validation/pcb-draft-3d.png`: KiCad render of the carrier and available standard
  component models. **ESP32, OLED and RS-232 assembled module models are absent**;
  the render is not an assembled-device or enclosure fit check.
- `pcb-placement-draft.pdf`: **1:1** front placement/pad/outline drawing. Print at
  100%, disable fit-to-page, and confirm the outer width is 82 mm before use.
  It includes the known module outlines and nominal STEP-derived DE-9 metal
  bounding projections; no guessed U1 body or case-wall geometry.

## Validation and limits

Run from the repository root with the system Python containing KiCad bindings:

```sh
/usr/bin/python3 -B hardware/PCB/validate_pcb_draft.py
/usr/bin/python3 -B hardware/PCB/validation/pcb-routing-check.py
```

The first script exports a **fresh saved-schematic netlist** and checks the actual
PCB pad assignments, component linkage, dimensions, layer count, nominal thickness,
mounting holes, track/via sizes and KiCad DRC. It never rewrites the PCB or project.
It reports the single expected U2 parity warning explicitly, and fails on any
other parity issue, DRC violation or unconnected item. Reports are retained in
`validation/pcb-parity-drc.json` and `pcb-validation-summary.json`.

The second independently checks continuous copper/hole/edge geometry and original
placement/net/UUID preservation against the initial unrouted snapshot. It needs
locally installed NumPy and Shapely in addition to pcbnew. It is not a substitute
for current-schematic net validation and is specific to this initial layout.

Results with KiCad **10.0.6**:

- **0 physical DRC errors/warnings; 0 unconnected items.**
- All saved-schematic pad nets match the PCB; **1 expected U2 footprint parity warning**.
- Independent minimum different-net/copper-to-NPTH gap **0.270544 mm**; minimum
  copper/NPTH-to-board-edge gap **1.900 mm**.
- All 9 electrical footprints and 4 board-only mounts retained; positions, outline
  and RF area revised as documented, with electrical linkage preserved.
- Startup `PROPERTY_ENUM` assertions from the local pcbnew binding are still
  emitted, but the checks complete successfully.

DRC uses the existing default ignored checks: `missing_courtyard`,
`track_not_centered_on_via`, `tuning_profile_track_geometries`,
`footprint_filters_mismatch`, `footprint_type_mismatch`. No new exclusions were
added to hide problems. **Missing module courtyards therefore remain an explicit
manual release gate**. The draft rules do not represent a chosen fabricator's
complete capability set. No electrical/hardware/fabrication tests were performed.

## Regeneration and project settings

Normal use is to **edit the native PCB in KiCad**, not regenerate it. The optional
`generate_pcb_draft.py` recreates the *unrouted* A1 placement and discards manual
PCB work only with explicit `--overwrite`; it refuses an open-project lock. A1 was
made by mutating the existing board, not running that generator. All A1 saves use
`SaveBoard(..., True)` to preserve user project settings. The original A0 creation
populated the minimal project with rules; this revision leaves those settings and
the schematic unchanged. Refresh device silkscreen and CAD envelope helpers after
any intentional regeneration or placement/routing changes.

`route_pcb_draft.py` requires NumPy and pcbnew. By default it never saves; replacing
existing tracks requires explicit `--route --overwrite --replace-routes`. Do not
run that over manual routing without a backup. It is a bounded initial-draft
router, **not** a general-purpose autorouter. See `validation/pcb-routing-summary.md`
for algorithm limits and commands. These scripts do not need downloaded packages
or services in the current environment and create no manufacturing outputs.

Before fabrication: qualify all module pin maps/footprints and connectors,
complete assembly courtyards and RF/USB/DE-9 checks, review power/return paths,
verify the existing USB power circuit and OLED pull-ups, confirm procurement and
case hardware, rerun ERC/DRC, and perform an independent hardware design review.