# 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](../descargas/index.md)**, 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.7.bin` | ⚠ publicado, sin prueba de banco (mismo código que V5 + `board_v4.h`); puente U13-P7 → SW4G1 opcional |
| **V5** — MCU soldado, lote de 15 | `hbox-v5-bringup_0.5.7.bin` | ⚠ vigente 26-sep (0.5.7: despertar de batería por reset del MCU; puente U13-P7 → SW4G1 como respaldo, ver [Descargas](../descargas/index.md)); 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:

```bash
# 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

1. **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.
2. Conecta el **USB del Blackpill** a la laptop.
3. **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.
4. **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`
5. Espera a **«Download complete»** y **«Verify successful»**. Si falla a la mitad, **no desconectes**:
   repite el paso 3 y vuelve a grabar.
6. Presiona **RESET**.

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

1. Abre el puerto serie a **115200 baudios**, con **guardar a archivo**.
2. Presiona RESET otra vez y captura el arranque.
3. 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.

4. Deja correr **10 minutos** con antenas conectadas y vuelve a mirar: `state` debe llegar a `RUN`,
   y `link` debe salir de `SRCH`.
5. **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):

```bash
# 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.7.bin
shasum -a 256 release/hbox-tarjetaV4_0.5.7.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.