espflash --- أداة كتابة البرنامج الثابت في محمّل إقلاع ROM لشريحة ESP32

توفر هذه الوحدة تطبيقاً مبسّطاً ESPFlash يتواصل مع محمّل إقلاع ROM الخاص بشريحة ESP32 عبر UART. وهي مخصصة للتحديثات داخل النظام للبرنامج الثابت لشريحة ESP32 على الوحدات المرافقة (على سبيل المثال، وحدة U-blox NINA-W10 المستخدمة على لوحات Arduino)، وليست بديلاً عن أداة esptool الكاملة. والميزات المتقدمة (محمّل الكعب، شرائح ESP الأخرى، الضغط بـ deflate، الإقلاع الآمن، إلخ) غير مدعومة عن قصد.

يبدّل المشغّل RESET و GPIO0 لوضع شريحة ESP32 في وضع التنزيل، ثم يصدر أوامر مؤطّرة بـ SLIP لقراءة حجم ذاكرة الفلاش، وتهيئة واجهة SPI، وكتابة صورة البرنامج الثابت والتحقق منها عبر بصمة MD5.

مثال للوحة Arduino Nano RP2040 Connect (اللوحة الوحيدة المدعومة من OpenMV حيث تكون espflash مجمّدة حالياً). دبابيس إعادة التعيين والتمهيد الخاصة بـ 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 الخاص بشريحة ESP32.

  • ‎reset‎ هو نسخة machine.Pin موصولة بخط RESET لشريحة ESP32، ومهيّأة كمخرج.

  • ‎gpio0‎ هو نسخة machine.Pin موصولة بخط GPIO0 لشريحة ESP32، ومهيّأة كمخرج.

  • ‎uart‎ هو نسخة machine.UART موصولة بدبابيس UART0 لشريحة ESP32. يجب تهيئته على معدل باود 115200 مع مهلة قراءة غير صفرية.

  • ‎log_enabled‎ يفعّل التسجيل المفصّل لأطر SLIP المتبادلة مع محمّل الإقلاع. مفيد لأغراض تصحيح الأخطاء فقط.

سيحاول المُنشئ استيراد hashlib. إذا كانت hashlib.md5 متاحة، فسيتم حساب بصمة MD5 الجارية المستخدمة من قبل ESPFlash.flash_verify_file() تلقائياً أثناء الكتابة.

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

تغيير معدل باود UART لمحمّل الإقلاع.

  • ‎baudrate‎ هو معدل الباود الجديد المراد التبديل إليه. إذا كان مختلفاً عن معدل الباود النشط حالياً، يُصدر أمر CHANGE_BAUDRATE إلى محمّل الإقلاع قبل إعادة تهيئة UART المحلي.

  • ‎timeout‎ محجوز وغير مستخدم حالياً.

لا يكون له أي تأثير إذا كان كائن UART الأساسي لا ينفّذ طريقة init().

bootloader(retry: int = 6) → bool

قيادة RESET و GPIO0 للدخول إلى وضع التنزيل لـ ROM شريحة ESP32 والتزامن مع محمّل الإقلاع.

  • ‎retry‎ هو عدد محاولات إعادة التعيين/التزامن قبل الاستسلام.

تُرجع True عند النجاح، وإلا فإنها تثير Exception.

flash_read_size() → int

قراءة معرّف JEDEC لذاكرة فلاش SPI وإرجاع حجم الفلاش بالبايت.

تثير Exception إذا كانت بتات الحجم المُبلّغ عنها خارج النطاق المتوقع 0x12-0x19.

flash_attach() → None

الاتصال بذاكرة فلاش SPI. يجب استدعاؤها مرة واحدة بعد bootloader() وقبل أي عملية قراءة/كتابة للفلاش.

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

تهيئة معاملات ذاكرة فلاش SPI.

  • ‎flash_size‎ هو إجمالي حجم الفلاش بالبايت، وعادةً ما تكون القيمة التي تُرجعها flash_read_size().

أحجام الكتلة والقطاع والصفحة ثابتة عند 64 KiB و 4 KiB و 256 بايت على التوالي.

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

كتابة صورة برنامج ثابت إلى الفلاش بدءاً من الإزاحة 0.

  • ‎path‎ هو مسار نظام الملفات للملف الثنائي للبرنامج الثابت المراد كتابته في الفلاش.

  • ‎blksize‎ هو الحجم بالبايت لكل كتلة بيانات تُرسل إلى محمّل الإقلاع. يجب أن يكون مضاعفاً لحجم القطاع.

تُحشى الكتلة الأخيرة بـ 0xFF حتى الوصول إلى blksize كامل. إذا كان دعم MD5 متاحاً، فسيتم تحديث بصمة MD5 الجارية أثناء الكتابة بحيث يمكن استدعاء flash_verify_file() بدون وسائط.

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

التحقق من محتويات الفلاش مقابل ملف برنامج ثابت.

  • ‎path‎ هو مسار نظام الملفات للملف الثنائي المرجعي للبرنامج الثابت؛ ويحدد حجمه عدد البايتات المراد التحقق منها.

  • ‎digest‎ هو بصمة MD5 اختيارية مُحسبة مسبقاً ومُرمّزة بالنظام الست عشري للملف. إذا كانت None، تُستخدم البصمة المُحسبة أثناء أحدث استدعاء لـ flash_write_file().

  • ‎offset‎ هو إزاحة الفلاش بالبايت التي يبدأ عندها التحقق.

تثير Exception إذا لم تكن هناك بصمة متاحة أو إذا كانت محتويات الفلاش لا تطابق البصمة المرجعية.

reboot() → None

إرسال أمر FLASH_END يوجّه محمّل إقلاع ROM لإعادة تشغيل شريحة ESP32 وتشغيل البرنامج الثابت المكتوب حديثاً. لا تُقرأ أي استجابة.