hbox-docs/docs/descargas/hbox-v5-bringup-README.md

title	tags	date
README del firmware hbox_v5_bringup (inglés)	project-drogheda firmware hbox_v5_bringup readme en	2026-09-27

hbox_v5_bringup — EinarBoard v5 first-flash bring-up firmware

Nota (sitio de documentación): este es el README del código fuente del firmware hbox_v5_bringup, en inglés, para quien compila. La tabla de binarios vigentes y sus SHA-256 es la de Descargas; la tabla «Release» de abajo se quedó en 0.5.1 y solo documenta cómo se nombran los archivos.

Bench-proves a newly assembled v5 board over USB-C J11 only. Never powers the RTK stack. 0.5.0: Modo B in-band $PHLG (server Salud column) on top of the 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.

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.

EinarBoard v4 (socketed Blackpill) — same sketch, board_v4.h

The v4 board is this design on a Blackpill (verified pad-by-pad against hbox-watchdog-v4.kicad_pcb); only ETH_INT moves to PB2. Build with the Blackpill variant and the board switch:

arduino-cli compile \
  --fqbn "STMicroelectronics:stm32:GenF4:pnum=BLACKPILL_F411CE,usb=CDCgen,xserial=generic,rtlib=nanofp" \
  --build-property "build.extra_flags=-DHBOX_BOARD_V4" \
  --output-dir out-v4 hbox_v5_bringup
mv out-v4/hbox_v5_bringup.ino.bin release/hbox-tarjetaV4_0.5.1.bin

PB2 is BOOT1 on the F411: enter DFU with USB only (W5500 unpowered) so INTn cannot hold BOOT1 high. The first console line must read board=EinarBoard v4 (HBOX v4).

EinarBoard V5.6 / V5.7 (0.7.0-pre2, 29-oct) — same sketch, board_v56.h + flash_guard.c

One binary for both boards (the 64 MCU pins are identical). The pilot carries the STM32F411RCT6 (256 KB, T47), so the build targets GENERIC_F411RCTX, keeps the EEPROM emulation in sector 5 (0x08020000) and caps the image at 128 KB below it. Without the two FLASH_* flags the sketch stops with #error; if they reach only the C++ files (not the core's C, where the EEPROM driver lives) flash_guard.c makes the link fail with undefined reference to hbox_flash_flags_in_c instead of producing an image that crashes on its first EEPROM read (audit A-07). The same .bin runs on a RET6.

export SOURCE_DATE_EPOCH=<value from CHANGELOG>   # release builds only: __DATE__/__TIME__ fixed = byte-identical rebuild (A-18)
arduino-cli compile \
  --fqbn "STMicroelectronics:stm32:GenF4:pnum=GENERIC_F411RCTX,usb=CDCgen,xserial=generic,rtlib=nanofp" \
  --build-property "build.extra_flags=-DHSE_VALUE=25000000UL -DHBOX_BOARD_V56 -DFLASH_DATA_SECTOR=5 -DFLASH_BASE_ADDRESS=0x08020000UL" \
  --build-property "upload.maximum_size=131072" \
  --output-dir out-v56 hbox_v5_bringup
cp out-v56/hbox_v5_bringup.ino.bin release/hbox-tarjetaV56_0.7.0-pre2.bin

The first console lines must read hbox-v5-bringup 0.7.0-pre2 and board=EinarBoard V5.6/V5.7 (HBOX v5); the in-band $PHLG version is 0.7.0p2. Bench only until the pilot passes its 8 criteria. Designators are the T43 ones on the silkscreen: SW1 = BOOT0, SW2 = RESET (the opposite of V5.5), USB-C DFU/console = J7, modem socket = J8/J9, LTC4040 = U14. DFU: hold SW1 → tap SW2 → release SW1. Technician procedure (ES), version 1.2: 06-Testing-Validation/2026-10-27_Drogheda_EinarBoard-V5.6-V5.7_Prueba-y-Flasheo_ES_v1.0.md (site: Prueba y flasheo V5.6/V5.7).

What 0.7.0-pre2 adds over 0.7.0-pre (details in CHANGELOG.md): the 10-min battery cycle with STOP + RTC (F-2; -DENABLE_DUTY=0 = continuous backup as in 0.7.0-pre), the SC16IS752 driver and serial test (F-3), the LIS2DH12 motion interrupt (F-5), the W5500 PHY in power-down outside -eth (E-3), robustness (dead Y2 → HSI, stuck I²C bus, no TMP102 → MCU sensor and no thermal re-arm) and every fix from the 29-oct audit (reviews A and C). Self-test: 21 PASS on USB only, 22 with /SYS5V (W5500_PHY). New keys: S serial test (J12 jumper + a second board in echo on J11), U RS-485 echo, Z STOP allowed/blocked, W W5500 in reset vs power-down (floor A/B with the PPK2); A now asks for Y within 10 s. Operator locks (B D C E Z U W and the P pause) expire after 2 h without USB. STOP only happens with the USB cable unplugged (the device state decides, not DTR, which the core never clears on unplug).

Bench Ethernet build (pilot criterion 5, the Ethernet part): add -DENABLE_ETH=1 to the flags above (needs arduino-cli lib install Ethernet; 2.0.2 on the build Mac) and copy it as release/hbox-tarjetaV56_0.7.0-pre2-eth.bin. On the RCT6 it fills 129 304 of 131 072 B, so it leaves out the battery cycle (it stays in continuous backup), the serial test keys, the STAT legend, the full help and the Y3 timing of SER_B_LAZO; the base build is 128 204 B. On V5.6/V5.7 the W5500 is U2 (U11 is the PCF8574) and the RJ45 is J6. The host simulator runs 64 V5.6/V5.7 scenarios on the build without Ethernet (see ../tools/hostsim_v5/README.md); the -eth path is not simulated.

Ethernet de banco (0.6.0-eth) — -DENABLE_ETH=1

Build separado; el binario de campo 0.5.8 no lo incluye. Necesita la librería Ethernet (arduino-cli lib install Ethernet).

arduino-cli lib install Ethernet
arduino-cli compile --fqbn "$FQBN_V5" \
  --build-property "build.extra_flags=-DHSE_VALUE=25000000UL -DENABLE_ETH=1" \
  --output-dir out-v5-eth hbox_v5_bringup
# V4:  --fqbn "$FQBN_V4" --build-property "build.extra_flags=-DHBOX_BOARD_V4 -DENABLE_ETH=1" --output-dir out-v4-eth

Sin PoE (J10 solo datos). Con 5 V presente el W5500 sale del reset, pide DHCP o cae a 192.168.7.2/24 y abre un TCP a 192.168.7.1:5010 (portátil con nc -lk 5010), por donde salen en espejo NMEA + $PHLG + $PHCG (0.6.2) + $PHEV + $PHID. Cable directo al portátil (Auto-MDIX) o cualquier switch. Overrides: -DETH_IP=a,b,c,d -DETH_SERVER_IP=a,b,c,d -DETH_SERVER_PORT=n -DETH_DHCP=0. Tecla E = on/off. Ver CHANGELOG 0.6.0-eth.

Simulador en PC (0.6.1, ampliado en 0.6.2 y 0.6.3) — ../tools/hostsim_v5

Antes de flashear un cambio del gobernador de carga, del riel o del $PHLG, correr el simulador: compila este sketch sin cambios contra stubs y un modelo eléctrico de la entrada de 5 V (calibrado con H0027) y revisa 54 escenarios de V5.5/V4 (ráfagas del módem, cable débil, desconexión del 24 V, hiccup, batería mala, pausa NTC, autoprueba r, vuelta del millis(), VDDA, formato del $PHLG/$PHCG y largo de las líneas que van al módem, tecla X; desde 0.6.3 también respaldo corto con el paquete bajo, motivo del reset en el RTC y espera de carga creciente, CHG_NOCHG, SLEEP con la media y la vigilancia del módem con histéresis) y, desde 0.7.0-pre, 64 de V5.6/V5.7 (módem con EN/RESET/LED/RTCM3, escalera, ruido en el LED, 5 V que rebota, caster caído, F9P sin alimentación, LFP, NTC, ignición; desde 0.7.0-pre2 el ciclo de batería con STOP, la prueba serie, el acelerómetro, el W5500 y los escenarios adversos de la auditoría del 29-oct), más un invariante de seguridad del cargador en cada vuelta del lazo y los de V5.6/V5.7 en cada escritura de PA1/PC3/PB5/PC1/PA9. En total 118 escenarios.

bash ../tools/hostsim_v5/run.sh                          # todo PASS = exit 0
bash ../tools/hostsim_v5/run.sh /ruta/a/otra/copia old   # mismos escenarios contra otra versión (p. ej. 0.6.0)

Necesita g++ con -m32 (Linux: g++-multilib); en un Mac con Apple silicon, dentro de Docker linux/amd64 — ver tools/hostsim_v5/README.md. No reemplaza la prueba de banco.

Prueba de largo de línea (0.6.2) — tecla X + ../tools/phtst_report.py

El módem (NTRIP Master) descarta las líneas largas que el MCU mete en banda (0.6.1: ninguna $PHLG de 125–131 caracteres llegó al servidor). Con Modo B activo, X manda 105 líneas $PHTST de largo exacto (100…140, controles de 60 y 6 pares pegados), ~50 s; X otra vez la cancela. Unos 15 s después de PRUEBA DE LARGO fin bajar el historial crudo de la unidad (monitor → ⬇ Historial crudo) y:

python3 ../tools/phtst_report.py H0027.txt

Da el límite por línea, si el módem corta por línea o por ráfaga, y si recorta las líneas en vez de descartarlas.

Diagnóstico de campo (0.6.3)

• Reset al volver el 5 V: tras ≥ 10 s de respaldo (0.5.9) y también tras ≥ 1 s si la media de 200 ms del paquete bajó de 3.70 V (BACKUP_WEAK_VBAT): con el paquete bajo el módem se apaga en el boost. Antes del reset sale en banda $PHEV PWR_RETURN_RESET,<razón>.
• Motivo del reset anterior: queda en los registros de respaldo del RTC (BKP16R–BKP18R; BKP19R lo usa la autoprueba RTC_BKP) y sale en consola (EVT RESET anterior: …) y en $PHEV BOOT … prev=<razón>[+carga] n=N. Con +carga (el 5 V se cayó < 10 s después de arrancar la carga) la espera de carga del arranque siguiente es 120 s × 2^n, hasta 30 min.
• CHG_NOCHG / STAT ltc=C8_BAJO: carga permitida, pulso de rearranque ya probado y el LTC4040 en «C/8» con el paquete bajo 3.80 V: revisar JP2/JP3/JP4 (flotación) y el paquete.
• STAT phlg_aire= phcg_aire= aire_max= y tecla t (aire> …, las dos líneas exactas que van al módem, con su largo): para separar «la unidad no manda» de «el servidor no muestra».
• Vigilancia del módem (STAT sag5= sagb= flat= modem=, $PHEV MODEM_DARK/MODEM_BACK, solo diagnóstico): 4 ventanas seguidas < 30 mV = oscuro, ≥ 50 mV = vivo (sag5 en 24 V, sagb en batería); las ventanas con un cambio de alimentación o de la corriente de carga no cuentan.

Puente 0.5.6 — MODEM_RST desde el MCU (V4 y V5)

El módem 4G (socket J7/J8) solo tiene su reset (MODEM_RST, J7.5) en el botón SW4G1. Desde 0.5.6 el firmware lo pulsa por el pin libre P7 del PCF8574 U13 (SOIC-16W, pin 12):

U13 pin 12 (P7)  ──|<──  SW4G1 pad 1 (MODEM_RST)        diodo Schottky BAT54 / 1N5819 (1N4148 sirve)
                cátodo   ánodo

• Verificar con M en consola (etapa ON): SW4G1 pad 1 debe caer a < 0.4 V durante 0.5 s y el módem reinicia (LEDs del módulo apagan y vuelven). STAT cuenta los pulsos en mrst=.
• Sin el puente, el firmware es idéntico salvo que el pulso no llega a nada.

Flash (DFU, J11)

Hold SW2 (BOOT0) → tap SW1 (RESET) → release SW2 → device 0483:DF11 appears. V5.6 / V5.7 (T43): the opposite — USB-C J7, hold SW1 (BOOT0) → tap SW2 (RESET) → release SW1, then dfu-util -a 0 -s 0x08000000:leave -D release/hbox-tarjetaV56_0.7.0-pre2.bin (bench only).

dfu-util -a 0 -s 0x08000000:leave -D release/hbox-v5-bringup_0.5.1.bin

or STM32CubeProgrammer → USB → Connect → Download release/hbox-v5-bringup_0.5.1.bin @ 0x08000000.

Release

File	Version	SHA-256 (first 16)	Size
release/hbox-v5-bringup_0.5.1.bin	0.5.1 (2026-09-18) — USE THIS (field-minimum + Modo B telemetry + diagnostics)	e1f351084e803306	79 804 B
release/superseded/hbox-v5-bringup_0.5.0.bin	0.5.0 — superseded (24-field $PHLG, no $PHEV)	98656ddcc4e209e2	77 312 B
release/superseded/hbox-v5-bringup_0.4.0.bin	0.4.0 — superseded (no in-band telemetry)	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.5.1 (2026-09-18) — diagnostics in band. $PHLG gains 5 append-only fields (25..29): up_s, pwr (VEH|BATT), v5min, vbat_min (lowest single-shot ADC reading in the 30 s window, sampled every loop iteration — catches the ms-scale LTE-burst sags that trip the LTC4040 PFI), bkp_n. New $PHEV,<up_s>,<CODE>,<detail>*CS event sentence on every state change (STACK_ON/OFF+reason, BACKUP_START/END, RECOVERY, LIMP/LIMP_END, TEMP_CUT/REARM, V5_LOW/LOST/OK, IGN_ON/OFF, SLEEP/SLEEP_END, MODOB_ON/OFF, BOOT), queued (6 deep) and sent in idle gaps ahead of $PHLG; STACK_OFF/MODOB_OFF are flushed synchronously (≤ 120 ms) before K1 releases. STAT adds v5min= vbatmin= bkp=. Server side: 02-Architecture-Software/htracker-patches/ (retranslator: 29-field parser, $PHEV store + events in status JSON, 5 diagnostic rules) — old parsers ignore the extras.
• 0.5.0 (2026-09-18) — Modo B: $PHLG in band. Once the stack is on and the F9P has been talking for 10 s, USART1 (PA10 tap / PA9) is started before K1 (PB5) is energised; the F9P TX2 stream then flows F9P → PA10 → MCU → PA9 → K1 NO → modem DIN byte for byte, and a $PHLG (same 24 fields) is injected every 30 s only after > 8 ms of line idle (a GGA is never split). Corrections modem → F9P stay on their direct wire. Fail-safe is hardware: PB5 low (reset, IWDG, any stack-off) = K1 NC = direct path. Prerequisites shipped with it: 256-byte UART rings (build_opt.h, static_asserted at compile), non-blocking SHT40 (two-phase kick/poll), console STAT/$PHLG deferred to line-idle gaps, K1 released before EEPROM.write (flash erase stalls the core) and before the r self-tests. B toggles Modo B (default allowed). STAT adds modoB= relay= phlg_aire=. Server: no change needed — retranslator._parse_phlg already accepts the sentence; units get the Salud column.
• 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.