Phase 1: establish Rev A hardware contract and PCB

.gitignore

@@ -4,3 +4,16 @@ sdkconfig
 sdkconfig.old
 dependencies.lock
 main/dev_config.h
+
+# KiCad transient/editor state and generated fabrication output. Keep native
+# project, schematic, PCB, symbol, footprint, and library-table sources tracked.
+*.lck
+*-backups/
+*.bak
+*.tmp
+_autosave-*
+*.gbr
+*.gbrjob
+*.drl
+*.pos
+*.rpt

README.md

@@ -51,9 +51,18 @@ about 130 °C at the heater/PTC region, and about 74–75 °C at the chassis. De
 sizing remains the rated 24 V / 200 W / 8.33 A case.
 
 That test did **not** validate the complete Jump Jet Q1/F2/PCB/connector/wiring
-path or installed operation. The authoritative `.kicad_pcb` is still missing.
-GPIO, ADC, thermistor, protection, and cooldown thresholds therefore remain TBD.
-The Sanyo Denki 9GA0424P3J001 is only a prototype fan candidate, not BOM-final.
+path or installed operation. Rev A.4.1 is the authoritative schematic baseline,
+and its [KiCad project source](hardware/kicad/JumpJet_RevA/README.md) is checked
+into this repository. The first Rev A PCB is Phase-1 work in progress; no
+fabrication-approved PCB or outputs exist. Checked-in source does not authorize
+heater or fan actuation. Detailed status and blockers are tracked in the
+[Phase 1 hardware register](docs/PHASE1_HARDWARE_REGISTER.md). GPIO, ADC,
+thermistor, protection, and cooldown thresholds therefore remain TBD.
+
+The replacement-fan direction is continuous fused 24 V and ground with separate
+open-drain PWM and tach feedback. The Sanyo Denki 9GA0424P3J001 remains a
+prototype candidate, not BOM-final; published facts and pending measurements are
+tracked in its [characterization record](docs/hardware/9ga0424p3j001-characterization.md).
 
 ## Safety boundary
 

ROADMAP.md

@@ -19,11 +19,19 @@ no phase passes its gate without the listed evidence.
 
 ## Phase 1 — freeze the hardware contract
 
-**Status:** next
-
-- review the current schematic, PCB layout, BOM, enclosure, and airflow path
-- confirm the exact ESP32-S3 module, flash size, GPIO map, and boot-strap constraints
-- identify heater, MOSFET, fans, thermistors, connectors, fuse, thermal cutoff, and switch
+**Status:** active
+
+- use Rev A.4.1 as the current authoritative schematic baseline
+- freeze the hardware contract and create/review the first Rev A PCB during Phase 1
+- review the BOM, enclosure, mechanical interfaces, and airflow path
+- confirm the exact ESP32-S3 Super Mini revision, flash size, GPIO map, and boot-strap constraints
+- implement a physically accessible, visibly labeled disconnect between
+  board-derived MCU 5 V and the Super Mini's directly coupled 5 V/USB-VBUS node;
+  seamless simultaneous board/USB power is out of scope for Rev A
+- identify heater, MOSFET, characterized four-wire fan channel, thermistors,
+  connectors, fuses, thermal cutoff, and switch
+- characterize the prototype fan before freezing interface-derived firmware
+  values or RPM/stall/proof thresholds
 - calculate steady and worst-case current, connector loading, copper temperature rise,
   MOSFET dissipation, gate drive, voltage drop, ADC range, and protection margins
 - create a system hazard analysis covering single faults and foreseeable misuse
@@ -39,7 +47,7 @@ protection question. Firmware constants may not be finalized before this gate.
 - implement board identity and force all heater control pins to their safe level at reset
 - implement calibrated ADC/thermistor conversion with open, short, rail, NaN, and
   implausible-reading classification
-- implement both fan outputs and any available tachometer or airflow feedback
+- implement the reviewed fan channel and tach-based fan proof
 - define the bounded fan-start/proof sequence and explicit proof-failure criteria from release-intent hardware evidence
 - implement the physical switch and define its electrical and software semantics
 - persist settings with bounds, schema versioning, corrupt-value fallback, and factory reset

TODO.md

@@ -6,19 +6,63 @@ implementation starts, and keep only the summary checkbox here.
 
 ## Needed from the current hardware design
 
-- [ ] Add or link the current KiCad schematic and PCB source
+- [x] Review the Rev A.4.1 schematic package and record it as the current
+  authoritative schematic baseline in the
+  [Phase 1 hardware register](docs/PHASE1_HARDWARE_REGISTER.md)
+- [x] Check the authoritative Rev A.4.1 KiCad project, hierarchical sheets,
+  project symbol/footprint libraries, and preliminary BOM into
+  `hardware/kicad/JumpJet_RevA/`
+- [ ] Create the first Rev A `.kicad_pcb` after the mechanical and electrical
+  layout blockers close
 - [ ] Add the current BOM with manufacturer part numbers and acceptable substitutions
-- [ ] Confirm the exact ESP32-S3 module/dev board and installed flash size
+- [x] Identify the physical controller module as an ESP32-S3 Super Mini
+- [x] Record the measured ESP32-S3 Super Mini envelope and provisional nominal
+  pin geometry
+- [ ] Verify the installed ESP32-S3 Super Mini flash size
+- [ ] Complete the production castellated footprint after the provisional land
+  geometry and exact registration, underside-contact isolation map, antenna
+  keepout, USB access envelope, and physical pin numbering are verified
 - [ ] Confirm the complete GPIO/ADC assignment, including boot strapping and USB pins
 - [x] Record standalone CZ4060 rated and measured power/current at 24 V
 - [ ] Validate the full Jump Jet Q1/F2/PCB/connector/wiring path at the 200 W / 8.33 A design basis
-- [ ] Finalize both fan part numbers, current, connector, PWM method, and tach availability (9GA0424P3J001 is prototype-only)
+- [x] Select the native four-wire fan architecture: continuous fused 24 V power,
+  separate open-drain PWM, and separate tach feedback
+- [x] Create the
+  [9GA0424P3J001 characterization record](docs/hardware/9ga0424p3j001-characterization.md)
+- [ ] Characterize the physical 9GA0424P3J001 specimen on arrival
+- [ ] Characterize the 9GA0424P3J001 prototype and finalize candidate-specific
+  pinout, current, connector, PWM/tach electrical details, RPM behavior, and
+  stall thresholds; it remains prototype-only
 - [ ] Record every thermistor part number, beta/Steinhart-Hart data, tolerance, and location
 - [ ] Confirm the MOSFET part, gate network, thermal environment, and default-off circuitry
 - [ ] Confirm fuse type/rating, independent thermal-cutoff part/rating, and physical placement
 - [ ] Define what the physical switch interrupts or commands
 - [ ] Add the latest enclosure/duct model and intended airflow direction
 
+### Current PCB/fabrication blockers
+
+- [ ] Define the board outline, mounting-hole coordinates, connector-facing
+  edges, and USB mechanical datum
+- [x] Measure ESP32 castellation width and the non-USB edge-to-first-castellation datum
+- [ ] Verify exact ESP32 body/pad registration on a 1:1 production-footprint plot
+- [x] Confirm the ESP32 underside has no mounted components
+- [ ] Map the exposed underside contacts and define the carrier isolation region
+- [ ] Identify and measure the actual ESP32 antenna keepout
+- [x] Measure the ESP32 USB-C shell envelope
+- [ ] Measure the USB-C mating-plug/cable-head envelope and define carrier-edge,
+  enclosure, and service-access clearances
+- [x] Establish the external 5 V / USB-C VBUS topology: the actual Super Mini's
+  exposed 5 V pin and USB VBUS are directly coupled for system-design purposes
+- [ ] Select, rate, and place the Rev A physical board-5-V disconnect; verify USB
+  access, service labeling, jumper/switch clearance, retention, and misuse visibility
+- [ ] Verify the Q1 footprint and multipad mapping
+- [ ] Verify the F2 holder footprint and service/removal clearance
+- [ ] Select TF1/TS1 parts and their mounting/thermal-coupling architecture
+- [ ] Select and verify J1, F1, and MOD1 parts and footprints
+- [ ] Characterize the production PSU current limit and complete fuse coordination
+- [ ] Close the aligned local mechanical constraint map before creating
+  fabrication-intent `Edge.Cuts`
+
 ## Firmware — immediate
 
 - [x] Add last-success sample age to `dc_prusa_status_t` in Dan's `dragon-core` fork
@@ -39,10 +83,22 @@ implementation starts, and keep only the summary checkbox here.
 ## Electrical and safety analysis
 
 - [ ] Draw the complete 24 V power and return path from supply through protection to loads
-- [ ] Calculate normal, startup, and credible fault current for heater plus both fans
+- [ ] Calculate normal, startup, and credible fault current for the heater plus
+  all final fan and auxiliary loads
 - [ ] Calculate connector/contact loading and wire ampacity with temperature derating
 - [ ] Calculate MOSFET conduction and switching loss at worst-case voltage, current, duty, and ambient
-- [ ] Check gate voltage/current, pull-down behavior, MCU reset behavior, and MOSFET SOA
+- [x] Implement separate `+5V_SYS_GATE` / `+5V_MCU` schematic domains and a
+  hardware-default-disabled heater-driver OE topology
+- [ ] Implement the adopted physical disconnect between board-derived MCU 5 V
+  and the Super Mini-side `+5V_MCU` / USB-VBUS tied node; removable jumper/shunt
+  is preferred but its part, rating, and footprint remain unresolved
+- [ ] Bench-verify that USB/service power cannot energize the gate-driver domain
+  or Q1 through every power-up, power-down, reset, brownout, and mixed-source state
+- [ ] Verify gate-driver partial-power-down behavior or provide equivalent isolation
+- [x] Retain a direct provisional Q1 gate pull-down independent of MCU and buffer state
+- [x] Add schematic test points for both 5 V domains, gate-driver OE, heater PWM
+  input, Q1 gate, and Q1 source reference
+- [ ] Check gate voltage/current, MCU reset behavior, switching waveform, and MOSFET SOA
 - [ ] Calculate trace/via current capacity and expected copper temperature rise
 - [ ] Calculate thermistor-divider voltage and ADC counts over open, short, and operating range
 - [ ] Define independent thermal-cutoff trip temperature from measured enclosure hot spots
@@ -53,7 +109,7 @@ implementation starts, and keep only the summary checkbox here.
 
 - [ ] Implement `jj_board` with safe-at-reset GPIO initialization
 - [ ] Implement ADC sampling, calibration, filtering, and explicit sensor status
-- [ ] Implement two fan channels and available fan/airflow proof
+- [ ] Implement the characterized fan channel and available fan/airflow proof
 - [ ] Define the bounded fan spin-up/proof timeout and the evidence that changes proof from pending to proven or failed
 - [ ] Implement physical-switch handling and debouncing
 - [ ] Implement bounded settings persistence with corrupt-NVS recovery
@@ -69,7 +125,7 @@ implementation starts, and keep only the summary checkbox here.
 
 - [ ] Finalize Jump Jet API v2 state and mutation schemas
 - [ ] Add chamber, outlet, and case temperature telemetry with sensor status
-- [ ] Add target, heater duty, both fan states, mode, and commissioning state
+- [ ] Add target, heater duty, fan command/proof state, mode, and commissioning state
 - [ ] Add PrusaLink connection, printer state, bed temperature/target, and sample age
 - [ ] Define optional Klipper/Moonraker integration for read-only printer state and bed-target telemetry, with the same stale-data fail-cold semantics as PrusaLink
 - [ ] Add visible interlocks, latched fault reason, and safe recovery guidance

docs/HARDWARE_BASELINE.md

@@ -1,4 +1,16 @@
-# Hardware baseline — not commissioned
+# Hardware baseline — Rev A Phase 1
+
+Rev A.4.1 is the current authoritative schematic baseline. Its
+[KiCad project source](../hardware/kicad/JumpJet_RevA/README.md) is checked into
+the repository. The checked-in source set currently contains no `.kicad_pcb`;
+creating the first Rev A PCB remains active Phase-1 implementation work.
+
+The detailed living source of truth for measurements, component candidates,
+design decisions, provisional values, blockers, and validation status is the
+[Phase 1 hardware register](PHASE1_HARDWARE_REGISTER.md). Presence in that
+register does not make a candidate BOM-final or approve fabrication.
+Checking in the KiCad source likewise does not make the design fabrication-ready
+or authorize heater actuation.
 
 ## Confirmed
 
@@ -9,17 +21,64 @@
   74–75 °C.
 - Full results: [CZ4060 characterization](hardware/cz4060-characterization.md).
 - The Sanyo Denki 9GA0424P3J001 is a prototype fan candidate, not BOM-final.
+- The Phase-1 replacement-fan contract is continuous fused 24 V and ground with
+  separate open-drain PWM and tach. The original Rev A.4.1 low-side switched
+  two-wire block is retained as baseline evidence, not production intent.
+- Published prototype facts and pending measurements are tracked in the
+  [9GA0424P3J001 characterization record](hardware/9ga0424p3j001-characterization.md).
+- Phase-1 schematic work separates the protected-24-V-derived
+  `+5V_SYS_GATE` actuator rail from the MCU logic domain. Bench measurements of
+  the actual Super Mini establish that its USB VBUS and exposed 5 V pin are one
+  effectively direct, bidirectional node: 4.993 V applied to the pin produced
+  4.992 V at VBUS; USB at 5.13 V produced 5.11 V at the pin; unpowered
+  continuity was confirmed.
+- Rev A therefore requires mutually exclusive installed/USB service power at
+  the module node. Board-derived MCU 5 V reaches the module only through a
+  physical disconnect that must be opened before powered USB attachment. A
+  removable jumper/shunt is preferred, but its part and footprint are not yet
+  selected. Seamless simultaneous source operation is out of scope.
+- USB shall not be routed through the carrier and must never source `+5V_SYS_GATE`.
+  The gate buffer cannot be powered from USB-only MCU power.
+- The heater driver now uses a hardware-default-disabled active-low OE topology:
+  an OE pull-up holds the driver disabled unless a separate open-drain enable
+  transistor is explicitly asserted. Generic `HEATER_GATE_EN` and
+  `HEATER_PWM_CMD` nets remain unassigned to controller pins.
 
 ## Not confirmed
 
-The authoritative `.kicad_pcb` remains missing. Q1, F2, PCB copper, connectors,
-wiring, installed airflow, the exact ESP32-S3 module, and the complete power path
-have not been validated together. The upstream Jetpack pin assignments are
-historical facts, not Jump Jet assignments.
+Q1, F2, PCB copper, connectors, wiring, installed airflow, the exact ESP32-S3
+module implementation, and the complete power path have not been validated
+together. The LMR36520 and SN74LV4T125 are strong candidates, not BOM-final;
+the regulator circuit, physical MCU service-disconnect implementation and rating,
+disconnect accessibility/labeling, and full power-transition bench matrix remain
+open. TPS2116-only automatic source selection is superseded because the module
+has no separately controllable USB and exposed-5-V nodes. The upstream Jetpack pin
+assignments are historical facts, not Jump Jet assignments.
+
+## Rev A MCU service-power states
 
-No GPIO, ADC, divider, thermistor conversion, fan/PWM method, protection threshold,
-thermal trip, cooldown criterion, or recovery threshold may be finalized without
-the corresponding source files and measured evidence.
+| State | Physical disconnect | Required outcome |
+|---|---|---|
+| Normal 24 V operation; USB absent | Closed | Board-derived MCU 5 V powers the Super Mini. `+5V_SYS_GATE` remains an independent 24-V-only actuator rail; firmware safety still controls actuation. |
+| USB service; 24 V absent | Open before USB attachment | USB powers only the Super Mini-side MCU logic node. Gate power is absent and the heater is physically incapable. |
+| USB service; 24 V present | Open before USB attachment | USB powers the MCU node; `+5V_SYS_GATE` may exist from 24 V but remains isolated and the default-disabled gate/OE architecture keeps the heater off unless every normal hardware and firmware condition is valid. |
+| Disconnect mistakenly closed while powered USB is attached | Invalid/misuse | Board 5 V and host VBUS can contend or backfeed. Silkscreen and accessible disconnect geometry must make this misuse obvious; Rev A does not promise safe seamless coexistence. |
+| USB removed while 24 V absent | Open | MCU loses power cleanly; no actuator domain may remain energized from USB capacitance or another path. |
+| 24 V removed while USB remains | Open | MCU may remain alive, but `+5V_SYS_GATE` collapses independently and firmware must truthfully report heater actuation unavailable. |
+
+No GPIO, ADC, divider, thermistor conversion, protection threshold, thermal trip,
+cooldown criterion, or recovery threshold may be finalized without corresponding
+source files and measured evidence. Fan interface values, production fan,
+tach electrical behavior, pulses/revolution, RPM versus duty, minimum reliable
+command, startup behavior, RPM/stall thresholds, and installed airflow/thermal
+performance remain unresolved. A model-specific 25 kHz candidate test point is
+not universal production policy.
+
+The newer Prusa-derived void is the preferred enclosure-space reference; the
+earlier smaller-void system-level incompatibility conclusion is superseded. PCB
+over the cold-air intake remains preferred and mechanically plausible, but the
+installed transform and aligned local constraint map are unresolved, so
+fabrication-intent `Edge.Cuts` remain blocked.
 
 ## Firmware consequence
 
@@ -28,5 +87,8 @@ GPIO, placeholder pin, PWM, ADC, thermistor conversion, or MOSFET actuation path
 The provisional numeric limit header was removed because unvalidated values are
 not a hardware contract.
 
+Heater actuation remains disabled while the safety-critical hardware design and
+validation progress.
+
 The build retains a provisional 4 MiB dual-OTA partition layout solely as an
 ESP32-S3 development baseline. It is not a release hardware constraint.