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 carrier draft.** It is **not fabrication-ready**.
See **`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.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.

## 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`, `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 |
| `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`, `rs232-footprint-notes.md` | Footprint origins, provisional pad/drill choices, validation and RS-232 adaptation attribution |
| `adafruit-research.md`, `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 |

Keep these files together 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 as a provisional
  reference for the selected **6253 male** module. Its footprint is deliberately
  **unassigned in the schematic** until the actual male header and mechanics are
  verified. The PCB draft assigns `Carrier:MAX3243_Reference_Provisional` on the
  PCB only, causing one documented footprint-parity warning. Its reference nets
  are routed for review, not male-board qualification. See `adafruit-research.md`
  and `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.2 kΩ, 1%, at least 0.125 W**, from each button input to 3.3 V.
  They provide nominal 1.5 mA contact current / 4.95 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` 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. One deliberate U2 footprint-parity warning
remains (PCB reference footprint versus blank schematic assignment). No added
DRC exclusions hide this warning. 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` 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. Mechanical outline registration and socket/drill selection remain pending. |
| RS-232 module | Adafruit MAX3243 full-pinout breakout; male is product 6253, female is 5988 | Published female CAD pin map and geometry verified; male mapping/fit remains provisional. Reference footprint used on PCB only; schematic assignment remains blank. |
| 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. External 2.2 kΩ pull-ups included. Live distributor stock remains unverified. |

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` 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. No male-specific module footprint is claimed verified.

## 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.
- Confirm the exact development board's regulator capacity and USB power-path
  behavior before finalizing the power design, especially with both USB ports attached.
- Display pull-up presence, resistance and termination rail must be checked on
  the actual module. Do not select external pull-up values without this information.
- Firmware enables internal button pull-ups; this carrier additionally uses 2.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 reports male/female board dimensions match;
  verify the selected male board against its manufacturer CAD.
- 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.
- Select readily available THT buttons; the existing random switches need not be reused.
- Case will be 3D-printed after PCB finalization. Include mounting provisions in
  the layout, but screw size, hole diameter and insert bosses are not yet selected.

## 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 seller drawing states 28 mm width and annotates 63 mm length; its 20 mm
  arrow is not header row spacing. Antenna extent and header-to-outline offsets
  are not fully dimensioned.
- 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.

## Remaining mechanical/electrical checks

1. OLED outline, mounting-hole placement, revised header position and display
   outline are user fit-verified. Select carrier header/socket pads and drills
   from the actual connector drawings.
2. Before final module outlines/courtyards, establish their registration to header
   centres, connector overhang and display position from drawings or measurements.
3. Verify power-path schematic/regulator capacity and OLED pull-up implementation.
   Photos alone do not establish those electrical properties.

The native schematic, local libraries and routed two-layer PCB draft are present.
Before fabrication, finish the above checks, qualify the male RS-232 module map
and footprint, and confirm procurement. The carrier now proposes an 82 × 80 mm
stepped outline and four Ø3.2 mm M3 mounting holes; case hardware is not yet fixed.
The PCB's RF reserve is a draft design allocation, not a verified module antenna
keepout. Module/USB/DE-9 clearances must still be established from actual hardware.