Commander1024/ESP32_Serial_Swiss_Army_Knife
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure project documentation

Browse Source 
Separate operator guides from development contracts, relocate
implementation notes under `docs/devel/`, and update cross-references
and
hardware tooling paths. Add getting-started, user administration, and
firmware update guides while preserving firmware behavior.
This commit is contained in:
Commander1024
2026-09-21 15:24:42 +02:00
parent 655f26a611
commit ab6a8010ba
43 changed files with 959 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files
hardware/PCB/README.md
+14 -11
View File
@@ -6,7 +6,7 @@ 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`** for placement, chosen dimensions/rules, provisional
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
@@ -22,24 +22,27 @@ the carrier. All 3.3 V and ground connections are explicit named nets.
| `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 |
| [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 outlines and ESP32 header guides after placement/routing; preserves copper and project settings |
| `db9-mechanical-notes.md`, `reference/db9-cad/` | STEP-derived metal dimensions, originals, source licenses and repeatable extraction/validation |
| [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 |
| `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`, `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 |
| [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 |
Keep these files together so project-relative libraries resolve. Standard 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.
@@ -75,8 +78,8 @@ modify footprints. The generated KiCad files are the editable design artifacts.
**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.
are routed for review, not male-board 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.
@@ -105,7 +108,7 @@ 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.
[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,
@@ -117,7 +120,7 @@ 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.
[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
@@ -136,7 +139,7 @@ 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.
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