espflash — ESP32 ROM-bootloader firmware-flasher

Deze module biedt een minimale ESPFlash-implementatie die via een UART communiceert met de ESP32 ROM-bootloader. Ze is bedoeld voor in-systeem-updates van de ESP32-firmware op begeleidende modules (bijvoorbeeld de U-blox NINA-W10-module die op Arduino-boards wordt gebruikt) en vormt geen vervanging voor het volledige esptool-hulpprogramma. Geavanceerde functies (stub loader, andere ESP-chips, deflate, secure boot, enz.) worden bewust niet ondersteund.

De driver schakelt RESET en GPIO0 om de ESP32 in downloadmodus te zetten en stuurt vervolgens SLIP-frame-commando’s om de flashgrootte uit te lezen, de SPI-interface te configureren, de firmware-image te schrijven en deze te verifiëren via een MD5-digest.

Voorbeeld voor de Arduino Nano RP2040 Connect (het enige door OpenMV ondersteunde board waarop espflash momenteel is bevroren). De reset- en boot-strap-pins van de NINA-W102 zijn respectievelijk RP2040 GPIO 3 en GPIO 2, en de UART0 van de NINA is bedraad naar RP2040 UART1 (TX = GPIO 8, RX = GPIO 9):

from machine import Pin, UART
from espflash import ESPFlash

reset = Pin(3, Pin.OUT)                                    # NINA RESET
gpio0 = Pin(2, Pin.OUT)                                    # NINA GPIO0
uart = UART(1, 115200, timeout=1000)

esp = ESPFlash(reset, gpio0, uart)
esp.bootloader()
esp.set_baudrate(921600)
size = esp.flash_read_size()
esp.flash_attach()
esp.flash_config(size)
esp.flash_write_file("NINA_FW.bin")
esp.flash_verify_file("NINA_FW.bin")
esp.reboot()

class ESPFlash

class espflash.ESPFlash(reset: 'machine.Pin', gpio0: 'machine.Pin', uart: 'machine.UART', log_enabled: bool = False)

Construeer een ESPFlash-object dat de ESP32 ROM-bootloader aanstuurt.

  • reset is een machine.Pin-instantie die verbonden is met de ESP32 RESET-lijn, geconfigureerd als uitgang.

  • gpio0 is een machine.Pin-instantie die verbonden is met de ESP32 GPIO0-lijn, geconfigureerd als uitgang.

  • uart is een machine.UART-instantie die verbonden is met de ESP32 UART0-pins. Ze moet geïnitialiseerd zijn op 115200 baud met een leestimeout die niet nul is.

  • log_enabled schakelt uitgebreide logging in van de SLIP-frames die met de bootloader worden uitgewisseld. Alleen nuttig voor debuggen.

De constructor zal proberen hashlib te importeren. Als hashlib.md5 beschikbaar is, wordt de lopende MD5-digest die ESPFlash.flash_verify_file() gebruikt automatisch berekend tijdens het schrijven.

set_baudrate(baudrate: int, timeout: int = 350) → None

Wijzig de baudrate van de bootloader-UART.

  • baudrate is de nieuwe baudrate waarnaar overgeschakeld moet worden. Als deze verschilt van de momenteel actieve baudrate, wordt er een CHANGE_BAUDRATE-commando naar de bootloader gestuurd voordat de lokale UART opnieuw wordt geconfigureerd.

  • timeout is gereserveerd en wordt momenteel niet gebruikt.

Heeft geen effect als het onderliggende UART-object geen init()-methode implementeert.

bootloader(retry: int = 6) → bool

Stuur RESET en GPIO0 aan om de ESP32 ROM-downloadmodus binnen te gaan en te synchroniseren met de bootloader.

  • retry is het aantal reset-/sync-pogingen voordat opgegeven wordt.

Geeft True terug bij succes, anders wordt een Exception opgeworpen.

flash_read_size() → int

Lees de JEDEC-ID van het SPI-flashgeheugen en geef de flashgrootte in bytes terug.

Werpt een Exception op als de gerapporteerde groottebits buiten het verwachte bereik 0x12-0x19 vallen.

flash_attach() → None

Maak verbinding met het SPI-flashgeheugen. Moet eenmaal worden aangeroepen na bootloader() en vóór elke flash-lees-/schrijfbewerking.

flash_config(flash_size: int = 2 * 1024 * 1024) → None

Configureer de parameters van het SPI-flashgeheugen.

  • flash_size is de totale flashgrootte in bytes, doorgaans de waarde die door flash_read_size() wordt teruggegeven.

De blok-, sector- en paginagroottes zijn vast ingesteld op respectievelijk 64 KiB, 4 KiB en 256 bytes.

flash_write_file(path: str, blksize: int = 0x1000) → None

Schrijf een firmware-image naar het flashgeheugen, beginnend bij offset 0.

  • path is het bestandssysteempad van de te flashen firmware-binary.

  • blksize is de grootte in bytes van elk gegevensblok dat naar de bootloader wordt gestuurd. Moet een veelvoud zijn van de sectorgrootte.

Het laatste blok wordt opgevuld met 0xFF tot een volledige blksize. Als MD5-ondersteuning beschikbaar is, wordt de lopende MD5-digest tijdens het schrijven bijgewerkt, zodat flash_verify_file() zonder argumenten kan worden aangeroepen.

flash_verify_file(path: str, digest: bytes | None = None, offset: int = 0) → None

Verifieer de inhoud van het flashgeheugen tegen een firmware-bestand.

  • path is het bestandssysteempad van de referentie-firmware-binary; de grootte ervan bepaalt het aantal te verifiëren bytes.

  • digest is een optionele vooraf berekende hex-gecodeerde MD5-digest van het bestand. Als None, wordt de digest gebruikt die tijdens de meest recente flash_write_file()-aanroep is berekend.

  • offset is de flash-offset in bytes waarbij de verificatie begint.

Werpt een Exception op als er geen digest beschikbaar is of als de inhoud van het flashgeheugen niet overeenkomt met de referentie-digest.

reboot() → None

Stuur een FLASH_END-commando dat de ROM-bootloader opdraagt de ESP32 opnieuw op te starten en de net geflashte firmware uit te voeren. Er wordt geen antwoord gelezen.