espflash — צורב קושחת ROM bootloader של ESP32

מודול זה מספק מימוש מינימלי של ESPFlash המתקשר עם ה-ROM bootloader של ESP32 דרך UART. הוא מיועד לעדכונים מתוך המערכת של קושחת ESP32 במודולים נלווים (לדוגמה, מודול U-blox NINA-W10 המשמש בלוחות Arduino), ואינו תחליף לכלי esptool המלא. תכונות מתקדמות (stub loader, שבבי ESP אחרים, deflate, secure boot וכדומה) אינן נתמכות במכוון.

הדרייבר מחליף את RESET ואת GPIO0 כדי להכניס את ESP32 למצב הורדה, ולאחר מכן שולח פקודות בפורמט SLIP כדי לקרוא את גודל ה-flash, להגדיר את ממשק ה-SPI, לכתוב את תמונת הקושחה ולאמת אותה באמצעות תקציר MD5.

דוגמה עבור Arduino Nano RP2040 Connect (הלוח היחיד הנתמך על ידי OpenMV שבו espflash מוקפא כרגע). פיני האיפוס וה-boot-strap של NINA-W102 הם GPIO 3 ו-GPIO 2 של RP2040 בהתאמה, וה-UART0 של NINA מחווט ל-UART1 של RP2040 (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)

יוצר אובייקט ESPFlash המפעיל את ה-ROM bootloader של ESP32.

• reset הוא מופע machine.Pin המחובר לקו RESET של ESP32, מוגדר כפלט.

• gpio0 הוא מופע machine.Pin המחובר לקו GPIO0 של ESP32, מוגדר כפלט.

• uart הוא מופע machine.UART המחובר לפיני UART0 של ESP32. עליו להיות מאותחל בקצב של 115200 באוד עם זמן קצוב לקריאה שאינו אפס.

• log_enabled מפעיל רישום מפורט של מסגרות ה-SLIP המוחלפות עם ה-bootloader. שימושי לניפוי באגים בלבד.

הבנאי ינסה לייבא את hashlib. אם hashlib.md5 זמין, תקציר ה-MD5 הרץ המשמש את ESPFlash.flash_verify_file() יחושב אוטומטית במהלך הכתיבה.

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

שינוי קצב הבָּאוּד (baud rate) של ה-bootloader UART.

• baudrate הוא קצב הבָּאוּד החדש שאליו יש לעבור. אם הוא שונה מקצב הבָּאוּד הפעיל כרגע, פקודת CHANGE_BAUDRATE נשלחת ל-bootloader לפני שה-UART המקומי מוגדר מחדש.

• timeout שמור ואינו בשימוש כרגע.

אין לכך כל השפעה אם אובייקט ה-UART הבסיסי אינו מממש מתודת init().

bootloader(retry: int = 6) → bool

הפעלת RESET ו-GPIO0 כדי להיכנס למצב הורדת ROM של ESP32 ולהסתנכרן עם ה-bootloader.

• retry הוא מספר ניסיונות האיפוס/סנכרון לפני ויתור.

מחזיר True בהצלחה, אחרת מעלה Exception.

flash_read_size() → int

קורא את ה-JEDEC ID של ה-SPI flash ומחזיר את גודל ה-flash בבתים.

מעלה Exception אם ביטי הגודל המדווחים נמצאים מחוץ לטווח הצפוי 0x12-0x19.

flash_attach() → None

התחברות ל-SPI flash. יש לקרוא לה פעם אחת לאחר bootloader() ולפני כל פעולת קריאה/כתיבה של flash.

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

הגדרת פרמטרי ה-SPI flash.

• flash_size הוא גודל ה-flash הכולל בבתים, בדרך כלל הערך המוחזר על ידי flash_read_size().

גדלי הבלוק, המגזר והעמוד קבועים על 64 KiB, 4 KiB ו-256 בתים בהתאמה.

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

כתיבת תמונת קושחה ל-flash החל מהיסט 0.

• path הוא נתיב מערכת הקבצים של קובץ הקושחה הבינארי לצריבה.

• blksize הוא הגודל בבתים של כל בלוק נתונים הנשלח ל-bootloader. חייב להיות כפולה של גודל המגזר.

הבלוק האחרון מרופד ב-0xFF ל-blksize מלא. אם תמיכת MD5 זמינה, תקציר ה-MD5 הרץ מתעדכן במהלך הכתיבה כך שניתן לקרוא ל-flash_verify_file() ללא ארגומנטים.

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

אימות תוכן ה-flash מול קובץ קושחה.

• path הוא נתיב מערכת הקבצים של קובץ הקושחה הבינארי הייחוס; גודלו קובע את מספר הבתים לאימות.

• digest הוא תקציר MD5 אופציונלי מקודד בהקסדצימלי ומחושב מראש של הקובץ. אם None, נעשה שימוש בתקציר שחושב במהלך הקריאה האחרונה ל-flash_write_file().

• offset הוא ההיסט ב-flash בבתים שבו מתחיל האימות.

מעלה Exception אם אין תקציר זמין או אם תוכן ה-flash אינו תואם לתקציר הייחוס.

reboot() → None

שולח פקודת FLASH_END המורה ל-ROM bootloader לאתחל מחדש את ESP32 ולהריץ את הקושחה הטרייה שנצרבה. לא נקראת תגובה.