0hmX/pcbgolf-routing-checkpoint-20261012

firmware-support/README.md

# H725100 firmware support for the static PCB MVP

This folder contains **compiled board-support code, not a complete working firmware image**. The authoritative PCBGolf schematic has four device ports. The available public firmware is the six-port [Panda Jungle predecessor at commit 78cf6990](https://github.com/commaai/panda/tree/78cf69904c332c599a297fcc2a09c08d10d429d5/board/jungle). Its GPIO map, ADC channels and number of ports differ; it also does not provide this board's hub and microSD drivers. The [challenge describes the circuit as loosely based on Panda Jungle](https://github.com/commaai/PCBGolf/blob/master/README.md). No exact original PCBGolf application was identified.

`pcbgolf_board.c` supplies actual CMSIS GPIO configuration, safe initial output levels, four port power controls, the 16 SBU ignition/relay controls, CAN standby and FDCAN2 alternate-port selection. `pcbgolf_imon.c` supplies measured-reference current conversion and per-port calibration. `board-pins.inc` is generated from the master netlist and manufacturer package data. All **60 active signals** pass package/function verification; `board-map.json` and `board-map.csv` include original and new pins, exact master nets, package pad numbers and peripheral functions. Old ADC pad labels have been replaced by PA2/PA3/PA7/PB0 in the master; the generator uses the actual master netlist rather than these old labels.

## Pin and peripheral contract

| Function | Port 1 | Port 2 | Port 3 | Port 4 |
|---|---|---|---|---|
| Power enable | PA0 | PA1 | PA4 | PA5 |
| IMON ADC | PC4, ADC1/4 | PB1, ADC1/5 | PC5, ADC1/8 | PA6, ADC1/3 |
| SBU1 ADC | PC2_C, ADC3/0 | PA7, ADC1/7 | PC0, ADC1/10 | PB0, ADC1/9 |
| SBU2 ADC | PC3_C, ADC3/1 | PA2, ADC1/14 | PC1, ADC1/11 | PA3, ADC1/15 |
| SBU1 IGN / RELAY | PD0 / PD1 | PD5 / PB14 | PC6 / PD11 | PD14 / PD15 |
| SBU2 IGN / RELAY | PD3 / PD4 | PD8 / PD10 | PD9 / PC7 | PA8 / PA9 |

PA2/PA3/PA7/PB0 are **SBU voltage measurements**, replacing PF7/PF8/PF9/PF10. The IMON package migration is PF11 → PC5. ADC1 uses 16-bit full scale; ADC3 uses 12-bit full scale in the predecessor driver. Application code must select the matching ADC instance, channel and configured resolution, perform ADC calibration and derive the real VREF/VDDA. Use the long 810-cycle acquisition setting as the starting point for the retained 100 kΩ SBU series resistors; analog settling and accuracy still need measurement. PC2_C/PC3_C analog switches are explicitly opened in `pcbgolf_gpio_init`.

CAN0 uses PB8/PB9, FDCAN1 AF9; CAN1 uses PB5/PB6, FDCAN2 AF9; CAN2 uses PD12/PD13, FDCAN3 **AF5**; CAN3 uses PB12/PB13, the alternate FDCAN2 AF9 pair. Standby controls are PB7/PB3/PA15/PB4. **CAN1 and CAN3 share a controller**, as in the original circuit. The selector leaves both standby signals disabled until the application explicitly enables the chosen transceiver. Stop/reinitialize FDCAN2 traffic before switching; a fourth independent simultaneous CAN controller is not provided.

USB uses PA11/PA12, AF10, the H725's internal **full-speed PHY**. The upstream connector and four external device links remain hub high-speed links. The MCU stays on hub downstream port 7; physical CH1–CH4 stay on hub ports 1–4; ports 5/6 remain unconnected. Hub `CFG_SEL2/1/0 = 111` is preserved: pins 13/42 tie high and SCL/CFG_SEL0 pin 41 is pulled high by R30. This support does not alter PortSwap, PortMap or hub straps and does not claim a working SMBus hub driver. PB10/PB11 map to I2C2 AF4, with R30/R28 pullups; software must respect the retained reset/configuration behavior before attempting transactions.

SDMMC1 uses PC12 clock, PD2 command, and PC8/PC9/PC10/PC11 data0–3, AF12. Card initialization, transfer/DMA/cache handling and filesystem code remain application work. The button is PC13; BOOT0 shares the physical BTN net. RGB LEDs are red PE4, green PE5, blue PE2, with high as the off state. PH0/PH1 retain the 25 MHz crystal; SWD PA13/PA14 remain unused pads in the source circuit.

The package and constrained functions are checked against [ST's STM32H725VGTx pin data](https://github.com/STMicroelectronics/STM32_open_pin_data/blob/master/mcu/STM32H725VGTx.xml) and [DS13311](https://www.st.com/resource/en/datasheet/stm32h725ve.pdf). Alternate-function constants are the manufacturer CMSIS/HAL definitions in the identified predecessor source. The build remains `STM32H725xx`, Cortex-M7, hard float, FPv5-D16. There is no supplied `.ioc` or `.syscfg` file to migrate; an independently generated CubeMX project must select **STM32H725VGT6 / LQFP100**, rather than ZGT6 / LQFP144.

## Direct-SMPS startup fix

The retained hardware uses the direct SMPS supply. `direct-smps.patch` adds a `PCBGOLF_H725100` override to the predecessor package detector; its existing accepted package codes omit LQFP100 and otherwise return `PACKAGE_UNKNOWN`. Apply this small patch to the pinned predecessor and pass **`-DPCBGOLF_H725100` to both the bootstub and application compilation**. Put the define in their common project flags, not only application flags. Both then select `PWR_CR3_SMPSEN` through the original clock initialization. The existing 25 MHz clock code is otherwise unchanged.

The support module deliberately does not write CR3 after startup: this register's supply configuration is locked after its first write. Cold-start, reset, bootstub, ROM recovery and application handoff remain hardware verification. The selected direct-SMPS topology is documented in [ST's power-extension header](https://github.com/STMicroelectronics/stm32h7xx-hal-driver/blob/master/Inc/stm32h7xx_hal_pwr_ex.h) and MCU supply documentation. The compile harness uses the predecessor's patched clock code and builds separate bootstub/application objects with the same override; it does not supply a bootloader image.

## Current monitor and safe power sequencing

R70–R73 are now 4.70 kΩ. The [TPS25944A datasheet](https://www.ti.com/lit/ds/symlink/tps25944a.pdf) gives nominal IMON gain 52.3 µA/A. Thus nominal scaling is **0.24581 V/A**, with the prior typical 0.8 µA offset corresponding to **3.76 mV**. For an initial estimate:

`I_A = max(0, (raw × measured_VREF / fullscale − zero_V) / gain_V_per_A)`

For each port, measure no-load zero, then a known current between 1 and 5 A; `pcbgolf_fit_imon` derives its own gain. Store four independent calibration records. Use actual ADC reference and configured resolution. The nominal constants are estimates, not calibration data. This API returns current; calculating watts also needs the actual port voltage, or an explicitly declared nominal 12 V assumption.

`pcbgolf_gpio_init` loads low port-enable latches before enabling outputs. Port power requests fail until `pcbgolf_set_vdda_health` receives a healthy measured rail of 3.0–3.6 V. A subsequently unhealthy reading disables all four outputs. This is a software interface, not a hardware supervisor: the caller must perform and periodically repeat a valid rail measurement. Other original startup code must not enable the eFuses beforehand. Hardware current/fault/rail sequencing and aggregate input budget remain separate acceptance checks.

## Reproduce the evidence

Run `python3 build.py` from this folder in the workspace. It regenerates the mapping from `work/candidates/two_layer_mvp/project/full.net`, checks and applies the startup patch to an owned scratch copy, then compiles:

- `pcbgolf_board.o` and `pcbgolf_imon.o` for `arm-none-eabi`, Cortex-M7, with `-Wall -Wextra -Werror` against the real STM32H725 CMSIS headers.
- `clock-bootstub.o` and `clock-app.o` from the patched predecessor clock code.
- A native host current-conversion test: 22 quantized load cases, independent measured 2 A calibration, no-load clamp and invalid-input rejection.

Set `PCBGOLF_CMSIS_INCLUDE` if the manufacturer header directory is elsewhere. Regeneration needs the recorded workspace sources; the generated C support, pin include and patch are standalone review artifacts. `build-evidence.json` records every command, source/object hashes, toolchain and actual results. The compiler is Apple Clang 21.0.0 targeting ARM. `arm-none-eabi-gcc` and SCons were not available, so no predecessor firmware build is claimed.

There is **no complete application link, signed/flashable image, board run, USB enumeration, SD transfer, CAN traffic, measured ADC/current calibration or tested recovery result**. This is suitable for the first static circuit MVP README as firmware migration support. A functioning application still needs the identified four-port contract integrated with its communication protocol and peripheral drivers, followed by hardware testing.