Skip to content

v1.0.30 — Heltec V4 boot reliability (DIO image header)

Choose a tag to compare

@jrl290 jrl290 released this 01 May 21:22

Fixes a bootloop affecting some Heltec V4 boards (reported on V4.3) caused by the v1.0.29 V4 binary having its image header marked QIO. The ESP32-S3 ROM bootloader trusts that header byte and configures the SPI controller for QIO before any of our code runs; if the flash chip / board strapping doesn't actually support QIO, the bootloader hangs in flash init and TG0 watchdog resets (rst:0x7 TG0WDT_SYS_RST, Saved PC inside ROM).

Fix: image header is now built as DIO (universally safe). The IDF 2nd-stage bootloader still runs bootloader_enable_qio_mode() which probes the flash chip's SFDP / Quad Enable bits at runtime and upgrades the SPI controller to QIO when the chip genuinely supports it. Steady-state flash throughput is unchanged on capable parts; cold boot adds ~50 ms for the probe.

Changes

  • platformio.inirtnode_heltec_v4 env: flash_mode = dio, arduino.memory_type = dio_qspi (PSRAM stays QSPI). V3 env: explanatory comment only.
  • flash.py — V4 board profile flash_mode qio→dio, so esptool merge_bin doesn't rewrite the header byte and undo the fix when packaging releases.
  • docs/index.html (web flasher) — Detect step now logs chip Variant (getChipDescription) and Flash ID (JEDEC mfg/dev) alongside Chip / Features / Flash size, so future bug reports include enough info to identify chip package and flash chip without guessing.

Notes for users

  • Web flasher: open https://jrl290.github.io/RTNode-HeltecV4/, click Detect, then Full install (since the bootloader image is being replaced).
  • CLI: python flash.py --board v4 --full.
  • Existing V3 boards: no functional change. Same binary behavior; refreshed image only because it's part of the same build.