ESP32_Serial_Swiss_Army_Knife/hardware/PCB/README.md

# KiCad 10 module carrier — schematic and routed PCB draft

Open **`serial-carrier.kicad_pro`** in KiCad 10, then open
**`serial-carrier.kicad_sch`**. A readable export is **`serial-carrier.pdf`**.
This is a native, editable schematic with actual connected nets, not an image
or a SKiDL-only netlist. **`serial-carrier.kicad_pcb` now contains a routed,
82 × 80 mm two-copper-layer A1 carrier draft with a top-left antenna notch,
USB toward the bottom and RS-232 toward the top.** It is **not fabrication-ready**.
See **[pcb-draft-notes.md](../../docs/devel/hardware/PCB/pcb-draft-notes.md)** for placement, chosen dimensions/rules, provisional
mechanical assumptions and validation. A review drawing is `pcb-placement-draft.pdf`.

The schematic contains the complete ESP32 development-board interface, MAX3243
breakout logic interface, I²C OLED, three Omron B3F-1000 buttons and three 2 kΩ
button pull-ups. USB connectors, regulator, reset/boot circuit, DE-9 and MAX3243
charge pump are already on their respective modules and are not duplicated on
the carrier. All 3.3 V and ground connections are explicit named nets.

## Current user acceptance and placement

See [user-acceptance.md](../../docs/devel/hardware/PCB/user-acceptance.md) for the exact group placements, nominal body clearances and evidence limits. Common body centreline is carrier-local X=56.970 mm; resistor bodies are centred in the RS-232/OLED gap with 2.0815 mm nominal clearance to each PCB. U1, U2, outline, carrier holes and USB placement are unchanged. R1–R3 are purchased 2 kΩ 1% metal-film parts; Omron B3F-1000 switches are also purchased.

The user accepts visual fit/USB clearance, male module mapping, M3 carrier/daughterboard and M2 display hardware, current RF reserve and power/ground routing. Intended/reported assembled module elevation is 10 mm, not an independently verified sum of the 8.5 mm female and described 2.5 mm male contributions. USB nonisolation is accepted; backfeed safety, regulator margin and RF qualification are not established. OLED backside pull-ups are confirmed by user, but their values/rail are unmeasured. Earlier pending-status language below is historical where superseded by this record.

PCB presentation uses **A3 landscape (420 × 297 mm)** instead of A4; the
carrier stays at absolute X=100…182, Y=100…180 mm. No origin, footprint,
routing or zone was moved. The 1:1 placement PDF includes the worksheet/title
block, clear of the PCB; `validation/pcb-placement-page.png` previews the full
page. Print at actual size on A3 for the 1:1 fit check, not “fit to A4”.
`update_presentation.py` removes the accepted USB/geometry/pinout/assembly
pending labels with lock/concurrent-edit guards and an exact-content audit.
RF qualification and connector/case-cutout cautions remain.

## Files and use

| File | Purpose |
|---|---|
| `serial-carrier.kicad_pro`, `serial-carrier.kicad_sch` | Native KiCad project and A3 single-sheet schematic |
| `serial-carrier.pdf` | Schematic review/print export |
| `serial-carrier.kicad_pcb` | Routed 82 × 80 mm stepped, two-copper-layer PCB draft |
| [pcb-draft-notes.md](../../docs/devel/hardware/PCB/pcb-draft-notes.md), `pcb-placement-draft.pdf` | PCB design decisions/limits and 1:1 placement review |
| `validation/pcb-draft.png`, `validation/pcb-draft-3d.png` | Copper/fab preview and carrier-only 3D render |
| `validate_pcb_draft.py` | Fresh schematic-to-PCB net checks, bounds/layers and DRC/parity report |
| `generate_pcb_draft.py`, `route_pcb_draft.py` | Optional destructive-regeneration tools with explicit overwrite guards |
| `add_device_silkscreen.py` | Refresh board-local OLED/RS-232 and measured ESP32 outlines/USB mouth markers after placement/routing; preserves copper and project settings |
| [db9-mechanical-notes.md](../../docs/devel/hardware/PCB/db9-mechanical-notes.md), `reference/db9-cad/` | STEP-derived metal dimensions, originals, source licenses and repeatable extraction/validation |
| `update_u1_graphics.py`, `validate_u1_update.py` | Guarded measured-U1 graphics integration and exact pre-update preservation / geometry / silkscreen regressions |
| `export_placement_pdf.py` | 1:1 PDF from saved board geometry; refuses stale embedded U1 graphics |
| `remove_draft_markers.py` | Guarded presentation-label cleanup with exact-content preservation audit; does not qualify fabrication |
| `add_db9_envelope.py` | Refresh nominal connector metal projections on Dwgs.User; not a case cutout or assembly clearance |
| `Carrier.kicad_sym`, `sym-lib-table` | Project-local module, switch and resistor symbols |
| `Carrier.pretty/`, `fp-lib-table` | OLED/ESP32/RS-232-reference provisional footprints; standard KiCad 10 switch/resistor/mounting-hole library references |
| `oled-fit-check.svg` | User-fit-verified OLED mechanical template |
| [footprint-notes.md](../../docs/devel/hardware/PCB/footprint-notes.md), [rs232-footprint-notes.md](../../docs/devel/hardware/PCB/rs232-footprint-notes.md) | Footprint origins, provisional pad/drill choices, validation and RS-232 adaptation attribution |
| [adafruit-research.md](../../docs/devel/hardware/PCB/adafruit-research.md), [button-notes.md](../../docs/devel/hardware/PCB/button-notes.md), `reference/` | Manufacturer evidence, pad maps and source/license records |
| `bom-draft.csv` | Draft procurement list and unresolved selections |
| `validate_schematic.py`, `validation/` | Repeatable netlist/firmware/ERC checks and exported evidence |
| `validate_footprints.py` | Native KiCad footprint geometry regression checks via system Python/pcbnew |
| `generate_schematic.py` | Optional stdlib-only initial design generator; not needed to open/edit in KiCad |

Development notes live in [docs/devel](../../docs/devel/README.md); the
[routing evidence summary](../../docs/devel/hardware/PCB/validation/pcb-routing-summary.md)
is retained there too. Keep CAD, libraries, assets and scripts together here so
project-relative libraries resolve. Standard KiCad
10 footprint libraries must be installed for the THT buttons, resistors and mounting holes.
SKiDL 2.3.0 is installed, but no SKiDL dependency is required for this native design.

**Normal validation from the repository root:**

```sh
python3 hardware/PCB/validate_schematic.py
```

This checks the current schematic without regenerating it, exports its netlist,
runs KiCad ERC, checks all 17 connected nets and all 15 firmware GPIO assignments,
and refreshes PDF/SVG review exports. It requires Python 3 and `kicad-cli`.
The expected-net snapshot records the initial design contract; intentional wiring
changes need a deliberate update to the checks and snapshot.

**Do not casually rerun `generate_schematic.py`:** it overwrites the schematic,
symbol library, library tables and expected-net snapshot, discarding subsequent
manual edits to those files. It preserves existing project settings and does not
modify footprints. The generated KiCad files are the editable design artifacts.

## Schematic conventions and design decisions

- U1 numbering is project-specific: viewed from the component side, antenna up
  and USB down, left row is 1–22 and right row is 23–44, both top-to-bottom.
  These numbers map directly to the local HW678 footprint, not to GPIO numbers
  or the official DevKit header reference designators. Signal order was transcribed
  from the user-supplied component-side board-label photos; the user confirmed
  matching board markings. This is photo/label evidence, not a continuity test:
  verify actual pin-to-function mapping before release, especially on clones.
- DS1 pins 1–4 are GND, VCC, SCL, SDA, front/display view with header at top.
- U2 pin numbering follows published Adafruit **5988 female** CAD for the selected
  **6253 male** module. The user confirmed the same pinout, header mapping and
  footprint as the reference. Both schematic and PCB now assign
  `Carrier:MAX3243_Reference_Provisional`; clean footprint parity is required.
  The identifier is unchanged; this assignment is not hardware or fabrication qualification. See [adafruit-research.md](../../docs/devel/hardware/PCB/adafruit-research.md)
  and [pcb-draft-notes.md](../../docs/devel/hardware/PCB/pcb-draft-notes.md); this is not a generic DE-9 footprint.
- No-connect crosses mean unused on the carrier, not disconnected internally.
  Native USB GPIO19/20, UART0 GPIO43/44, memory-conflicting GPIO35–37 and the 5 V
  header are not connected to carrier circuitry.
- U1 pin 1 (3V3) and pin 22 (GND) model the onboard supply as power outputs for
  ERC; the other duplicate rail pins are passive. This does not verify the
  regulator's capacity or USB power isolation. GPIO9 is modeled as a programmable
  bidirectional pad; firmware **must use open-drain mode** for OFF. ERC does not
  enforce that configuration or model the breakout's internal OFF pull-up.
- Selected buttons are Omron B3F-1000 with their verified KiCad THT footprint.
  Added R1–R3, **2 kΩ, 1%, at least 0.125 W**, from each button input to 3.3 V.
  They provide nominal 1.65 mA contact current / 5.445 mW dissipation while pressed,
  rather than relying on the internal pull-up for the silver-contact rated load.
  Firmware's internal pull-ups and debouncing remain enabled; no firmware changes
  are required. Final supply tolerance/load budget still needs checking.
  DIN0207 axial footprints are selected; exact resistor MPNs remain pending.
- External I²C pull-ups are **not assigned guessed values**. Verify OLED onboard
  pull-ups, resistance and rail before electrical sign-off and add appropriately
  sized carrier pull-ups if needed. The OLED must be powered from 3.3 V.

## Validation status

KiCad CLI 10.0.6 loaded the schematic and exported PDF, SVG and XML netlist.
ERC reported **zero errors/warnings**, with no project exclusions added. Exact
net memberships, all 44 U1 pins and firmware GPIO assignments were checked.
The PDF was rendered and visually inspected for layout/readability. Both local
footprints loaded in KiCad's native footprint loader. Two retained regression tests
passed with `/usr/bin/python3 -B hardware/PCB/validate_footprints.py`; the binding
emits startup PROPERTY_ENUM assertions but completes the checks. See
[footprint-notes.md](../../docs/devel/hardware/PCB/footprint-notes.md) for scope and limitations.

OLED PCB/header/display/mounting-hole geometry was physically fit-verified by
the user. This does **not** validate connector drills, male RS-232 geometry,
electrical operation, power budget, procurement or fabrication.

The routed PCB draft has **0 physical DRC violations and 0 unconnected items**;
a fresh netlist-to-PCB check passes with **zero schematic-parity issues**,
including the user-confirmed U2 footprint assignment. No DRC exclusions were
added. Missing courtyards are ignored by default DRC
and remain a manual release check. Run `/usr/bin/python3 -B
hardware/PCB/validate_pcb_draft.py` from the repository root; see
[pcb-draft-notes.md](../../docs/devel/hardware/PCB/pcb-draft-notes.md) for the complete verification scope and remaining gates.
No firmware build or device tests were run: this PCB work did not modify firmware.

## Evidence and components

Repository sources: `../../docs/wiring.md`, `../../src/board_pins.h`,
`../../docs/electrical_tests.md`, and `../../README.md`.

| Assembly | Repository identification | Footprint status |
|---|---|---|
| ESP32 development board | User confirmed HW-678 V0.0.0 markings and S3-N16R8 shield, two USB-C ports | Two 22-pin rows; nominal 2.54 mm pitch and 25.40 mm row spacing supported by simultaneous breadboard fit. Measured planar outline and visual fit accepted by user; finished-hole process remains unqualified. |
| RS-232 module | Adafruit MAX3243 full-pinout breakout; male is product 6253, female is 5988 | Eagle pin map/PCB geometry and STEP metal dimensions extracted. User confirms identical male pinout/header/footprint, visual fit and pin-by-pin review. Reference footprint assigned in schematic and PCB. |
| Display | 128×64 yellow/blue I²C OLED, address 0x3c; Amazon ASIN B0F13SSSFB | 26 mm square board, 22.50 mm hole spacing, Ø2 mm holes and centred header 1.50 mm from top edge are user-fit-verified. Local footprint assigned; header pad/drill selection remains provisional. |
| Three buttons | Omron B3F-1000; previous, select, next; normally open to ground, active low | Datasheet and `Button_Switch_THT:SW_TH_Tactile_Omron_B3F-100x` pad mapping verified. Purchased per user; external purchased 2 kΩ 1% metal-film pull-ups included. |

Adafruit manufacturer CAD starting point:
https://learn.adafruit.com/adafruit-rs-232-full-pinout-level-shifter-breakout/downloads

Published female-module Eagle CAD and its header map were retrieved and verified;
see [adafruit-research.md](../../docs/devel/hardware/PCB/adafruit-research.md) for pinned revision, hashes, attribution and geometry.
The original files and CC BY-SA 3.0 notices are retained in `reference/`; they
remain under their upstream license. Omron reference documents retain their
manufacturer notices. The CAD-parts repository's STEP and MIT license are separately
retained under `reference/db9-cad/`. External metal geometry is used for the male
module on the user's explicit equivalence confirmation. The user separately
confirmed electrical mapping and visual fit; connector threads, tolerances and
final case cutout are not independently qualified.

## Verified logical connections for the existing firmware profile

This table uses signal names, **not physical connector positions**. The schematic
and its local symbols additionally capture the project's physical pad numbering.
The wiring guide warns that compatible ESP32 boards may have different layouts.

| ESP32 connection | Peripheral connection |
|---|---|
| 3V3 | RS-232 Vin; existing I²C OLED VCC |
| GND | RS-232 GND; OLED GND; one contact of each button |
| GPIO17 | RS-232 TX |
| GPIO18 | RS-232 RX |
| GPIO15 | RS-232 RTS |
| GPIO16 | RS-232 CTS |
| GPIO7 | RS-232 DTR |
| GPIO5 | RS-232 DSR |
| GPIO4 | RS-232 DCD |
| GPIO6 | RS-232 RI |
| GPIO8 | RS-232 VLD |
| GPIO9 | RS-232 OFF (active-low shutdown; open-drain drive) |
| GPIO11 | Existing I²C OLED SDA |
| GPIO12 | Existing I²C OLED SCL |
| GPIO10 | Previous/back switch to GND |
| GPIO13 | Select/confirm switch to GND |
| GPIO14 | Next switch to GND |

## Electrical constraints from the repository

- Keep UART0 / GPIO43 and GPIO44 available through the onboard USB-UART bridge.
- Reserve GPIO19 and GPIO20 for onboard native USB.
- Existing firmware profile powers RS-232 Vin and OLED VCC from 3.3 V, not 5 V.
- User reports successful 3.3 V module operation and accepts nonisolated USB power.
  Regulator margin and USB backfeed safety remain unverified, especially with two powered hosts.
- User confirms backside OLED I²C pull-ups and operation without extras.
  Resistance and termination rail are unmeasured; no external values are invented.
- Firmware enables internal button pull-ups; this carrier additionally uses 2 kΩ
  external pull-ups for the selected buttons' contact-current requirement.
- RS-232 OFF uses the breakout's onboard pull-up; GPIO9 releases it to enable.
- The breakout is not galvanically isolated; signal grounds are common.
- Preserve access to both development-board USB connectors and account for the
  antenna keepout using the exact board/module documentation.

## User-confirmed design direction

- ESP32 purchase: https://www.amazon.de/dp/B0F3XMYYQY
- OLED purchase: https://www.amazon.de/dp/B0F13SSSFB — I²C, not SPI.
- Both Amazon URLs returned an access-check page on inspection; the ASINs alone
  do not establish a verified manufacturer drawing or footprint.
- Use the male Adafruit breakout. User confirms dimensions, pinout/header/footprint
  equivalence and completed a pin-by-pin module connection review.
- Carrier for complete modules: soldered module headers for final assembly,
  sockets for beta testing without a case. Header pitch, row spacing, drill size
  and socket clearance must be validated against selected hardware.
- Power only through the ESP32 development board's USB connectors, typically a
  powerbank or the serial peer's USB port, with common ground. Do not introduce
  another carrier power input or assume simultaneous USB supplies are isolated.
- User purchased Omron B3F-1000 THT buttons and 2 kΩ 1% metal-film resistors.
- Case will be 3D-printed after PCB finalization. User approves M3 carrier holes,
  10 mm brass standoffs into heat inserts, M3 daughterboard screws and M2 display
  hardware. Exact insert/boss dimensions and screw lengths are not supplied.

## User-supplied mechanical evidence

- ESP32 listing pictures show HW-678 V0.0.0; user confirms matching markings and
  actual shield S3-N16R8. Disregard the listing picture's N8R2 marking for memory
  identification and its erroneous USB labels: native USB is GPIO19 D− / GPIO20 D+.
- ESP32 raw measurements: header first-to-last centres initially 52.6 mm, revised
  to 52.93 mm; row spacing measured 25.00 mm. User subsequently confirmed both
  rows fit a standard breadboard simultaneously without forcing. Use nominal
  2.54 mm pitch (53.34 mm over 21 intervals) and 25.40 mm row spacing based on
  that fit check, not the raw caliper measurements. Verify with a 1:1 print before fabrication.
- ESP32 actual user measurements supersede the seller's 28 × 63 mm drawing:
  main PCB **56.07 × 28.09 mm**, excluding the antenna projection. Top/component
  view, antenna up and USB down: antenna projects **6.89 mm** above the main PCB,
  inset **5.41 mm left / 5.05 mm right**. Derived antenna width **17.63 mm**,
  overall length **62.96 mm**, antenna centre **0.18 mm right** of PCB centre.
- Header end offsets were initially approximately 1.5 mm; user accepted **1.365 mm**
  top/bottom to preserve the breadboard-confirmed 53.34 mm span. Left-edge-to-left-row
  centre distance is also approximately **1.365 mm**. Preserve 25.40 mm row spacing:
  the resulting right margin is **1.325 mm**, not an independently measured offset.
  These modelling offsets are not a claim of micron-level measurement accuracy.
- Both USB-C metal shells are **8.87 mm wide**, with opening faces flush with the
  main PCB bottom edge. Left shell's outside left edge is **4.16 mm** from the PCB
  left edge; right shell's outside right edge is **3.66 mm** from the PCB right edge.
  User accepts USB placement and mating-plug clearance visually; shell depth/height remain unmeasured.
- The library and routed board's embedded U1 now record these bounds on F.Fab;
  USB mouths are width spans only, not complete connector outlines. Measured
  board-local silkscreen, 1:1 placement PDF and SVG/PNG/3D previews are refreshed. See
  `../../docs/devel/hardware/PCB/footprint-notes.md` for coordinates and limits.
- OLED actual PCB outline measured by user: 26 × 26 mm, superseding the seller's
  28.7 × 27.8 mm dimensions. Seller's 4.1 mm height remains unverified.
- OLED front view, connector at top: GND, VCC, SCL, SDA from left to right,
  confirmed on actual module. Raw first-to-last span revised from 7 mm to 7.49 mm;
  user confirms standard breadboard fit and agrees nominal pitch is 2.54 mm
  (7.62 mm span).
- OLED mounting-hole diameter measured as 2 mm. User approved the latest edge
  measurements as superseding the earlier 22.16 mm hole-spacing measurement:
  centres are 1.75 mm from adjacent edges, giving 22.50 mm spacing in both axes.
- User verified the template's PCB outline and mounting-hole placement against
  the actual OLED module: both fit perfectly. Header-pin centres were subsequently
  corrected to 1.50 mm from the top PCB edge, superseding 0.75 mm. The header row
  is therefore 0.25 mm nearer the top edge than the upper mounting-hole centres.
- User measured the display outline margins: top 4.5 mm, bottom 5 mm, left 1 mm,
  right 0.5 mm. On the 26 mm PCB this defines a 24.5 × 16.5 mm rectangle from
  (1, 4.5) to (25.5, 21), shown dashed in the template. This records the supplied
  display boundary, not an independently verified active-pixel area or case cutout.
- User subsequently confirmed the revised template is "about a perfect fit",
  validating the PCB outline, mounting-hole placement, corrected 1.50 mm header
  position and display outline against the actual module. This is a user-reported
  mechanical fit check, not electrical or fabrication validation.
- User explicitly approved a horizontally centred header, superseding the earlier
  approximate 7.33 mm hole-to-pin measurements.
- Approved coordinates in mm, viewed from the display side with the header at
  the top, origin at the top-left PCB corner, X right and Y down:
  GND (9.19, 1.50), VCC (11.73, 1.50), SCL (14.27, 1.50), SDA (16.81, 1.50).
  Mounting-hole centres: (1.75, 1.75), (24.25, 1.75), (1.75, 24.25),
  (24.25, 24.25), each diameter 2 mm. Board outline: (0, 0) to (26, 26).
- `oled-fit-check.svg` is a 1:1 mechanical template of that geometry. Print at
  100%, without fit-to-page, and verify its 20 mm scale before checking the module.
  Crosshairs denote header centres, not specified pad or drill diameters. This
  template is not a KiCad footprint or a fabrication file.

## Current acceptance checklist and evidence limits

- [x] Component dimensions and visual physical fit accepted by user, including USB placement/clearance and RS-232 prong clearance.
- [x] Male Adafruit pinout/header/footprint equivalence and pin-by-pin module connection review confirmed by user; existing U2 schematic assignment retained with clean parity.
- [x] M3 carrier holes, 10 mm brass standoffs into heat inserts, M3 daughterboard screws and M2 display hardware approved.
- [x] Omron B3F-1000 and 2 kΩ 1% metal-film resistors purchased per user.
- [x] Existing 3.3 V supply operation and OLED onboard pull-ups reported; no extra I²C pull-ups needed in reported operation.
- [x] Nonisolated USB power, existing RF reserve and power/ground routing accepted by user.
- [ ] Independently verified regulator margin, USB backfeed safety, OLED pull-up resistance/rail and manufacturer RF/EMC qualification are not available.
- [ ] Detailed fastener lengths/insert dimensions, final case cutout, tolerance/height envelopes and fabrication-process qualification remain outside this acceptance.

The intended/reported 10 mm assembled elevation is not independently measured;
8.5 + 2.5 = 11 mm is not evidence of actual mated height. User acceptance closes
the corresponding review gates, not these factual evidence limits. Missing
module courtyards still limit automated assembly checks. No new hardware tests,
firmware changes, Gerbers, order or certification are implied.