Reflasheo de unidades HBOX — solo en taller

Para: Alan y Daniel (ejecución) · ingeniería (generación del binario) Versión: 1.0 · 18-sep-2026 · Responsable: Leo Rodríguez

1. Cuándo se reflashea y cuándo no

Reflashear es una prueba diagnóstica, no una reparación: sirve para contestar «¿el problema desaparece con firmware nuevo?». Si la unidad tiene un corto, un conector roto o una batería hinchada, el firmware no va a arreglar nada.

!!! danger "Dos reglas que no se rompen" 1 · Solo en taller, nunca sobre la máquina. Un flasheo interrumpido deja la unidad muerta. Si eso pasa en la mesa, se vuelve a intentar; si pasa arriba de un RTG, hay que bajarla otra vez.

**2 · Primero la evidencia, después el flasheo.** El flasheo borra la memoria del equipo
(temperatura máxima, recuperaciones, causa del último arranque) y sustituye el firmware que
estaba fallando. **Haz y sube las capturas del diagnóstico antes de tocar el botón.** El acta de
banco bloquea este paso hasta que el archivo de captura esté subido.

Situación	¿Reflashear?
Ya hiciste el diagnóstico y las capturas están subidas	Sí
La unidad tiene corto, humedad o daño visible	No — enviar a Querétaro
No sabes qué firmware trae	Primero anótalo (línea `BOOT` de la captura)
La unidad está instalada en la máquina	No. Se desmonta primero
No encuentras el `.bin` correcto en Descargas	No inventes: pregunta a ingeniería

2. Qué binario le toca a cada unidad

Los binarios viven en Descargas, con su versión y su SHA256. Cada generación de tarjeta tiene el suyo y no son intercambiables: la polaridad del control de carga está invertida entre generaciones, así que un binario equivocado puede dejar la batería cargando cuando debería estar cortada.

Generación de tarjeta	Binario	Estado
V3 — EinarBoard 1.0 (RTK-003, RTK-006, RTK-014), Blackpill	`hbox-tarjetaV3_4.0.0.bin`	⚠ publicado, sin prueba de banco
V4 — Blackpill + PCF8574/W5500/SC16IS752	`hbox-tarjetaV4_0.5.2.bin`	⚠ publicado, sin prueba de banco (mismo código que V5 + `board_v4.h`)
V5 — MCU soldado, lote de 15	`hbox-v5-bringup_0.5.2.bin`	⚠ vigente 24-sep (reporte cada 10 min en batería); antes flashear, servidor con soporte `DUTY`

Si el renglón dice pendiente, no hay binario aprobado todavía: el flasheo de esa generación está detenido hasta que ingeniería lo publique (§6).

3. Qué necesitas

Laptop con STM32CubeProgrammer (o dfu-util).
Cable USB con datos (muchos cables de carga no llevan datos — si la laptop no ve nada, prueba otro).
El .bin descargado del sitio, con su SHA256 verificado.
La unidad en la mesa, energizada solo por el USB.

Verifica el archivo antes de flashear:

# macOS / Linux
shasum -a 256 hbox-tarjetaV3_X.Y.Z.bin
# Windows (PowerShell)
Get-FileHash .\hbox-tarjetaV3_X.Y.Z.bin -Algorithm SHA256

Debe coincidir carácter por carácter con el que publica SHA256SUMS.txt. Si no coincide, descárgalo otra vez; si sigue sin coincidir, no lo uses y avisa.

4. El flasheo, paso a paso

Anota el firmware que traía. De la captura del diagnóstico, la línea BOOT,…,fw=3.0.3,…. Va en el acta. Sin este dato el reflasheo no sirve como prueba.
Conecta el USB del Blackpill a la laptop.
Entra a modo DFU:
- Mantén presionado BOOT0.
- Presiona y suelta RESET (NRST).
- Suelta BOOT0.
- En la laptop debe aparecer «STM32 BOOTLOADER» (identificador 0483:DF11). Si no aparece: repite la secuencia; si sigue sin salir, el cable no lleva datos o el MCU no arranca.
Graba el binario en la dirección 0x08000000:
- STM32CubeProgrammer → conectar en USB/DFU → Open file → Download.
- o bien: dfu-util -a 0 -s 0x08000000:leave -D hbox-tarjetaV3_X.Y.Z.bin
Espera a «Download complete» y «Verify successful». Si falla a la mitad, no desconectes: repite el paso 3 y vuelve a grabar.
Presiona RESET.

5. Verificación — el flasheo no termina hasta aquí

Abre el puerto serie a 115200 baudios, con guardar a archivo.
Presiona RESET otra vez y captura el arranque.
Comprueba:

Aparece la línea BOOT con la versión nueva en fw=.
El LED vuelve a parpadear (no se queda apagado ni en parpadeo rápido permanente).
Empiezan a salir líneas TLM, cada pocos segundos.
Ningún EVT de falla repitiéndose sin parar.

Deja correr 10 minutos con antenas conectadas y vuelve a mirar: state debe llegar a RUN, y link debe salir de SRCH.
Sube esta captura al acta, junto con la de antes del flasheo. Las dos juntas son la prueba de si el firmware cambió algo.

Resultado	Qué sigue
Arranca y se estabiliza en `RUN`	Candidata a reinstalar — coordina con ICAVE
Arranca pero repite la misma falla	El firmware no era la causa → enviar a Querétaro
Ya no arranca después del flasheo	Repite DFU con otro cable; si sigue, enviar a Querétaro

6. Para ingeniería — cómo se genera el binario

(Esta sección no es para el técnico: es para quien publica el .bin.)

Hoy el repositorio no contiene binarios compilados de V3 ni de V4. Los .bin están en .gitignore a propósito. Y hay una diferencia importante entre las dos generaciones:

Generación	Código fuente	Qué falta
V3	✅ `04-Source-Code/firmware/blackpillrtkcode_v4/` (4.0.0): la lógica de v3.0.3 + telemetría en banda	Probarlo en banco (RTK-003 / RTK-006)
V4	✅ `hbox_v5_bringup/` (0.5.1) + `board_v4.h` — la V4 es la V5 en un Blackpill	Compilar para Blackpill y probarlo en banco

Un binario por tarjeta. blackpillrtkcode_v3 (3.0.4) queda solo como referencia: es la lógica que corre hoy en campo pero sin telemetría en banda, así que el monitor no la ve.

El buen dato es que V3 no depende de ninguna librería externa — solo <Arduino.h> y <math.h> — así que basta el core de STM32.

Compilación reproducible con arduino-cli (verifica el FQBN contra tu instalación del core STM32duino antes de darlo por bueno):

# 1. toolchain (una sola vez)
brew install arduino-cli          # o descárgalo de arduino.cc
arduino-cli config init
arduino-cli config add board_manager.additional_urls \
  https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json
arduino-cli core update-index
arduino-cli core install STMicroelectronics:stm32

# 2. confirma que tu core trae la variante Blackpill (es una opcion de GenF4, no una placa aparte)
arduino-cli board details -b STMicroelectronics:stm32:GenF4 | grep -i blackpill

# 3. compila — usb=CDCgen es obligatorio: sin el, la consola USB queda muda
cd ~/Documents/Claude/Projects/Drogheda/04-Source-Code/firmware
arduino-cli compile \
  --fqbn "STMicroelectronics:stm32:GenF4:pnum=BLACKPILL_F411CE,usb=CDCgen,xserial=generic,rtlib=nanofp" \
  --output-dir release/ \
  blackpillrtkcode_v4/

# 4. nómbralo por tarjeta + versión y saca su huella
mv release/blackpillrtkcode_v4.ino.bin release/hbox-tarjetaV3_4.0.0.bin
shasum -a 256 release/hbox-tarjetaV3_4.0.0.bin | tee -a release/SHA256SUMS

# 5. V4: mismo codigo que V5, compilado para Blackpill con board_v4.h
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 release/ hbox_v5_bringup/
mv release/hbox_v5_bringup.ino.bin release/hbox-tarjetaV4_0.5.2.bin
shasum -a 256 release/hbox-tarjetaV4_0.5.2.bin | tee -a release/SHA256SUMS

El destino de tarjeta ya viene bien por omisión: el propio .ino trae TARGET_EINARBOARD 1 y TARGET_PROTO 0, que es lo correcto para la flota desplegada — las unidades de campo son EinarBoard 1.0 corriendo v2/v3 (así lo dice el V4-PLAN.md). Solo habría que tocarlo si vas a flashear una tarjeta de protoboard, y en ese caso se edita el .ino, no se pasa por la línea de comandos.

!!! warning "El flag de destino de tarjeta no es cosmético" TARGET_EINARBOARD y TARGET_PROTO invierten la polaridad del control de carga (en producción CHRG_EN en alto = carga apagada; en protoboard CHRG_RUN en alto = carga encendida). Compilar con el destino equivocado puede dejar la batería cargando justo cuando el firmware cree que la está protegiendo por temperatura — precisamente la falla #1 del RCA.

Antes de publicar:

Compilado con el TARGET_ correcto para la generación de tarjeta.
Probado en banco en una unidad real, no solo compilado.
Verificada la polaridad del control de carga sobre hardware.
Publicado en docs/descargas/ con versión en el nombre y su línea en SHA256SUMS.txt.
Anotado en el CHANGELOG.md del repositorio de firmware, con la fecha.
Actualizada la tabla de §2 de este documento.

9.0 KiB Raw Blame History