# hbox_v5_bringup — EinarBoard v5 first-flash bring-up firmware

Bench-proves a newly assembled v5 board over USB-C **J11** only. Never powers the RTK stack.
0.4.0 field-minimum: AUTO by default (stack self-powers with 5 V on P2, kept on through 5 V loss), watchdog, fan, link recovery, LEDs; charge OFF. Bench mode: `P`+`Y` stack ON/OFF, `n` NMEA monitor (fix 4 = RTK FIX). Console (0.2.1): CR+LF lines, `EVT` on every state change, named `STAT` every 5 s, `$PHLG` every 10 s in the fleet v3.x layout (server-parseable).
Checks: HSE 25 MHz + USB CDC · LSE Y4 · I2C: PCF8574 0x20 / SHT40 0x44 / TMP102 0x48 /
SC16IS752 0x4D · gauge + RGB LED walk · ADC · digital inputs. Prints PASS/FAIL, then a
`STAT` line every 2 s. Console commands: `r` rerun · `g` gauge walk · `i` I2C scan · `h` help.

Procedure for technicians (ES): `06-Testing-Validation/2026-09-15_Drogheda_EinarBoard-v5_Procedimiento-Prueba-y-Flasheo_ES_v1.0.md`

## Build
STM32duino core 3.x (`STMicroelectronics:stm32`). Target is the **generic F411RE**, not the Blackpill.
```bash
arduino-cli compile \
  --fqbn "STMicroelectronics:stm32:GenF4:pnum=GENERIC_F411RETX,usb=CDCgen,xserial=generic,rtlib=nanofp" \
  --build-property "build.extra_flags=-DHSE_VALUE=25000000UL" \
  --output-dir out hbox_v5_bringup
```
`rtlib=nanofp` is required — the default newlib-nano build prints nothing for `%f`, so every voltage
and temperature line would be blank. `SystemClock_Config()` is overridden in the sketch (HSE 25 MHz → 96 MHz, USB 48 MHz) because the
generic variant defaults to HSI, which is not accurate enough for USB.

## Flash (DFU, J11)
Hold **SW2** (BOOT0) → tap **SW1** (RESET) → release SW2 → device `0483:DF11` appears.
```bash
dfu-util -a 0 -s 0x08000000:leave -D release/hbox-v5-bringup_0.4.0.bin
```
or STM32CubeProgrammer → USB → Connect → Download `release/hbox-v5-bringup_0.4.0.bin` @ `0x08000000`.

## Release
| File | Version | SHA-256 (first 16) | Size |
|---|---|---|---|
| **`release/hbox-v5-bringup_0.4.0.bin`** | **0.4.0 (2026-09-17) — USE THIS (field-minimum, AUTO by default)** | `a8de74b3d7768e9d` | 75 524 B |
| `release/superseded/hbox-v5-bringup_0.3.0.bin` | 0.3.0 — superseded (AUTO opt-in, no watchdog/fan/recovery) | `d4608c739cef2661` | 72 860 B |
| `release/superseded/hbox-v5-bringup_0.2.1.bin` | 0.2.1 — superseded (no AUTO mode; stack OFF on 5 V loss) | `78b34f4603550c05` | 70 084 B |
| `release/superseded/hbox-v5-bringup_0.2.0.bin` | 0.2.0 — superseded (LF-only console, no EVT/$PHLG) | `8491625d494f9ee1` | 64 780 B |
| `release/hbox-v5-bringup_0.1.1.bin` | 0.1.1 — superseded (no bench mode) | `91ca6f87a86686be` | 55 104 B |
| `release/hbox-v5-bringup_0.1.0.bin` | 0.1.0 — SUPERSEDED (no float printf, ETH_CS driven) | `1a9a77ae479c8f86` | 41 040 B |

## Changelog
- **0.4.0** (2026-09-17) — **field-minimum ("-fm")**: what a unit needs to be left on a machine for days **without the production
  charge governor**. **AUTO is now the default** (only the flash byte `0x5A` means MANUAL; a virgin board powers the stack by itself).
  IWDG 16 s watchdog · fan policy = v3.0.3 (vehicle 5 V+ign → 100 %; battery → thermostat 48/45 C on the hottest sensor) ·
  link recovery (no valid NMEA 60 s after a 90 s grace → 5 s stack cycle, max 1/5 min; RTK lost 15 min after having it → one cycle,
  max 1/30 min; 3 NMEA-loss cycles → LIMP, stack stays ON) · gauge DB1-4 (3.60/3.75/3.90/3.97 V, −0.10 hyst) + RGB state via PCF8574
  (green RTK · blue on/no RTK · magenta on/no NMEA · yellow battery · red off) · thermal cut tbat/tntc ≥ 60 C, re-arm < 55 C, warning 50 C ·
  low battery cut 3.40 V, re-arm 3.70 V or 5 V return · `$PHLG` now carries `recoveries`, `limp`, `fan_pwm`, `state` PWRCYC/SLEEP, `link` LIMP
  (verified against `retranslator._parse_phlg` + web_monitor badges). **CHARGE STAYS OFF — the pack is one-shot until the production port.**
- **0.3.0** (2026-09-17): **AUTO mode** (`A` toggles, persisted in flash via STM32duino EEPROM emulation — survives reset and
  power loss; factory default = MANUAL). In AUTO the stack powers itself 3 s after 5 V is present on P2, no console needed.
  **Battery-backup test:** in AUTO, losing the 5 V input keeps the stack ON from the pack and logs `EVT BACKUP inicio` /
  `BACKUP fin dur= nmea_durante= vbat=` (NMEA continuity through the dropout = LTC4040 backup proven); stack dropped at
  vbat < 3.40 V or tbat/tntc > 50 C (`AUTO(pausa)` until 5 V is re-plugged). MANUAL keeps 0.2.x behaviour (stack OFF on 5 V loss).
  `STAT` adds `modo=` and `backup=`. Charge stays OFF in every mode. RAM +8 KB (EEPROM sector buffer).
- **0.2.1** (2026-09-17): console made monitorable — every line ends CR+LF (no more PuTTY staircase); `EVT up=…` line on every
  state change (stack ON/OFF with reason and the expected voltages, ignition edge, 5 V present/lost, charger status/fault edges,
  first NMEA frame / NMEA lost >5 s, GGA fix-quality change, stack refused/cancelled); `STAT` every 5 s with named values
  (`ign=ON`, `chrg=idle`, `flt=none`, `tntc=n/c`, `i2cerr=`, `t_on=`, `nmea=`/`bad=`); `$PHLG` every 10 s + after each stack change,
  **same 24-field layout + XOR checksum as fleet fw v3.x** (verified against `htracker/retranslator.py::_parse_phlg`; `fw=0.2.1-bu`,
  `state=BENCH|RUN`, `link=SRCH|DEGR|OK`); NMEA checksum verified (bad frames counted as `rxbad`); `P` arms non-blocking (10 s window),
  `Y` confirms; new commands `t` ($PHLG now), `l` (field legend), `v` (multimeter checkpoints for the stack gate: SYS5V/PWR_CTRL/GATE_LS/SW_5V);
  stack auto-OFF if 5 V is lost; `v5=…(BAJO)` + EVT when VEH5V drops under 4.6 V (LTC4040 PFI zone: PFI divider R51 270k/R52 100k
  → 4.44 V falling, backup VSYS 4.79 V via R53 499k/R54 100k) — the 24-Jul modem-hiccup mechanism, now visible in the log. Build: no-op ctags + explicit definition order (arduino/ctags unreachable from the build host).
- **0.2.0** (2026-09-17): bench mode for the assembled unit — `P`+`Y` powers the RTK stack (only with 5 V on P2),
  `P` again turns it off; `n` streams `$GxGGA` from the simpleRTK2B UART1 (PA3, 115200) for 20 s with fix/sats/HDOP;
  `STAT` shows `stack=` and the last GGA. Charge stays disabled, K1 released. Uses the core's `Serial2` (USART2).
- **0.1.1** (2026-09-16, audit): build with `rtlib=nanofp` (floats printed blank in 0.1.0); `ETH_CS` now
  `INPUT_PULLUP` instead of driving HIGH into the unpowered W5500; reset cause reports `PIN` only when
  `PINRSTF` is set (else `UNKNOWN`).
- **0.1.0** (2026-09-15): first build.

## ⚠ Do not flash `blackpillrtkcode_v3` (v3.0.3) on v5
Its `PIN_BATLED1..4` = PB12–PB15 are the W5500 SPI2 bus on this board. `board_v5.h` is the
verified v5 pin map — the production v5 firmware should include it rather than redefine pins.