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

Compact two-layer PCB — A1 draft

Current status (2026-09-22): User acceptance and group alignment supersedes the earlier pending user-fit, USB-clearance, male-map, procurement and mounting-hardware items below. Original research/evidence remains historical; acceptance is not independent qualification.

Paths in prose point to the retained hardware artifacts or neighboring development notes. Commands keep their stated working directory; repository-root paths remain root-relative.

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

Measurement update — embedded U1, silkscreen and exports

The user has now supplied ESP32 main-PCB, antenna and USB mouth geometry; see footprint-notes.md and the hardware README. The library HW678 footprint contains these measured F.Fab bounds. Embedded U1 now has the same four shapes and two measurement-limit annotations; generic library captions are omitted to avoid colliding with existing board labels. Silkscreen, PDF and SVG/PNG/3D previews are refreshed. Existing footprint fields, all existing non-generated UUIDs, pads/nets, placement, routing, edges, RF reserve and project settings are unchanged. Old hidden U1 status/description fields are retained historical metadata, not evidence that planar measurements are missing. RF requirements, full USB envelopes and assembly heights remain pending; the antenna rectangle is not an RF keepout.

At unchanged A1 U1 placement, the measured main PCB occupies carrier-local X=6.635…34.725, Y=21.635…77.705 mm; the projecting antenna occupies X=12.045…29.675, Y=14.745…21.635 mm. USB mouths are at Y=77.705 mm, 2.295 mm inside the carrier bottom edge, so flush-with-module USB does not mean flush-with-carrier access. Review mating-plug clearance before accepting placement; no relocation, rerouting or RF sign-off is implied by this update.

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. A1 moved U1 down by 19 mm; this measurement integration retains that placement and uses the user-accepted approximate header datum.
• 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.970, 36)	OLED module upper-left PCB corner; display faces up
R1 / R2 / R3	(42.160 / 53.160 / 64.160, 32.6685)	Axial pull-ups in the gap between RS-232 and OLED
SW1 / SW2 / SW3	(41.720 / 53.720 / 65.720, 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 ../../../../hardware/PCB/validation/pcb-a0-before-reposition.kicad_pcb. The board area is 58.76 cm²; its bounding rectangle is 65.6 cm².

H1–H4 are user-approved Ø3.2 mm NPTH M3 clearance holes. The user selected 10 mm brass standoffs into heat inserts; see the current acceptance record. 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. Exact insert dimensions remain unspecified. The user intends/reports 10 mm assembled module elevation, not independently measured; see user-acceptance.md.

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.
• 938 segments after incremental group-alignment repair, signal width 0.25 mm, 3.3 V and GND width 0.50 mm.
• 41 through vias after repair, 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 planar PCB/antenna/USB-mouth offsets are now recorded. Antenna clearance and USB access must still 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 Carrier:MAX3243_Reference_Provisional in the schematic and PCB. 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.

../../../../hardware/PCB/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 user has now confirmed male pinout/header/footprint equivalence and reviewed connections pin by pin. U2 is assigned in both schematic and PCB; validators require zero schematic parity warnings, without exclusions.

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 now has measured body/antenna outlines, replacing the header-row guides and HEADER GUIDES label. Silkscreen is clipped inside the stepped carrier with 0.22 mm additional edge/mask clearance; the off-carrier antenna projection remains visible only on F.Fab. Two 0.30 mm strokes mark the 8.87 mm USB mouth spans, replacing coincident 0.12 mm body-edge strokes. Wider strokes receive correspondingly wider clearance. No USB depth or RF keepout is inferred. Existing button/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:

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

The script first verifies the saved U1 measured graphics against the library. It 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

PCB presentation labels have been removed: title suffix draft, revision suffix DRAFT, front-silkscreen DRAFT - NOT FOR FAB, and the title-comment prefix NOT FOR FABRICATION - (including the PDF exporter). The generator no longer emits these labels. Specific technical cautions, dimensions, geometry, hidden metadata and footprint identifiers remain; artifact filenames are unchanged. This is a presentation change, not fabrication approval. The schematic and its exports are outside this PCB-only cleanup.

remove_draft_markers.py performs the guarded, idempotent cleanup and audits that no other parsed board content or project settings change. The U1 regression now permits exactly these label edits against its unchanged historical baseline, without relaxing geometry/pad/net/routing checks. Fresh PCB DRC, U1/silkscreen regressions and both footprint tests pass; the expected U2 parity warning remains. PDF/SVG/PNG/3D outputs were regenerated and visually reviewed after cleanup.

• ../../../../hardware/PCB/validation/pcb-draft.svg / ../../../../hardware/PCB/validation/pcb-draft.png: combined copper/outline/fab review.
• ../../../../hardware/PCB/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.
• ../../../../hardware/PCB/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 and measured U1 planar geometry; no guessed USB depth, RF keepout or case-wall geometry.

Refresh the embedded measurement graphics and PDF without replacing the footprint:

/usr/bin/python3 -B hardware/PCB/update_u1_graphics.py
/usr/bin/python3 -B hardware/PCB/add_device_silkscreen.py
/usr/bin/python3 -B hardware/PCB/export_placement_pdf.py

Both board-writing helpers refuse PCB Editor locks and concurrent board changes, use SaveBoard(..., True), and check unchanged project settings. The PDF exporter verifies embedded geometry instead of overlaying the library; only review captions change on its temporary plotting board. Print at 100%, not fit-to-page.

Preview refresh commands (repository root, KiCad and Inkscape installed):

kicad-cli pcb export svg --mode-single --layers F.Cu,B.Cu,F.SilkS,F.Fab,Dwgs.User,Edge.Cuts --sketch-pads-on-fab-layers --page-size-mode 2 --output hardware/PCB/validation/pcb-draft.svg hardware/PCB/serial-carrier.kicad_pcb
inkscape hardware/PCB/validation/pcb-draft.svg --export-type=png --export-width=1800 --export-filename=hardware/PCB/validation/pcb-draft.png
kicad-cli pcb render --width 1600 --height 1200 --side top --quality high --output hardware/PCB/validation/pcb-draft-3d.png hardware/PCB/serial-carrier.kicad_pcb

KiCad's SVG trailing whitespace was normalized after export (git diff --check passes); the rendered geometry is unchanged. PDF and previews were visually reviewed.

The board-area SVG crop omits outside-board review captions/parts of the DE-9 projection; use the full-page PDF for the complete placement drawing.

Validation and limits

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

/usr/bin/python3 -B hardware/PCB/validate_pcb_draft.py
/usr/bin/python3 -B hardware/PCB/validation/pcb-routing-check.py
/usr/bin/python3 -B hardware/PCB/validate_footprints.py
/usr/bin/python3 -B hardware/PCB/validate_u1_update.py
/usr/bin/python3 -B hardware/PCB/reference/db9-cad/validate.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 requires zero parity issues, DRC violations and unconnected items, including the retained user-confirmed U2 assignment. Reports are retained in ../../../../hardware/PCB/validation/pcb-parity-drc.json and ../../../../hardware/PCB/validation/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.

Measurement-integration validation with KiCad 10.0.6:

• All five commands above pass. New validate_u1_update.py compares the complete parsed board against validation/pcb-before-u1-measured.kicad_pcb, excluding only owned silk and six new U1 graphics. Snapshot and project hashes are pinned; full pad/net/UUID/placement/routing/edge/zone/settings preservation passes.
• Measured embedded/library geometry, silk regeneration idempotence, carrier/notch clipping, two exact USB mouth markers and a stale-geometry negative control pass; 91 generated silk items. U1 refresh byte-idempotence also passed; an already current U1 now returns without writing. Evidence: hardware/PCB/validation/pcb-u1-update.json.
• The historical A0 pcb-routing-preservation.py does not pass: it stops on its historical serial-carrier.kicad_prl protected hash, already stale for this working state. Its older exact-footprint contract also predates measured U1 additions. Historical script/reports were not weakened or rebaselined; the new A1 pre-update comparison is the preservation evidence for this change.
• PCB, project and schematic retain their existing content except the authorized board graphics. No firmware/assets, reroute, upload, erase or hardware test.

Historical measurement-integration results (current alignment results are in user-acceptance.md):

• 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 ../../../../hardware/PCB/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.

../../../../hardware/PCB/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.