CircuitPython pozwala uruchamiać programy w Pythonie bez kompilowania każdego szkicu. Na obsługiwanej płytce z natywnym USB zapisujesz code.py na dysku CIRCUITPY, a interpreter wykonuje nową wersję. Najważniejszym krokiem instalacji jest jednak dobranie obrazu do konkretnej płytki, nie tylko napisu „ESP32-S2”.

Co pokazuje materiał z warsztatu?

W materiałach IMZ zachowały się trzy zrzuty: wybór obrazu na stronie CircuitPython, zapis .bin narzędziem esptool oraz uruchomiona konsola REPL. Historyczna próba używała profilu Saola 1 w/WROOM i wydania 10.0.0-beta.3. Zrzut zapisu pokazuje ESP32-S2 z 4 MB Flash i bez PSRAM, lecz nie identyfikuje jednoznacznie całej płytki.

To cenna obserwacja udanego zapisu i uruchomienia interpretera w tamtej konfiguracji. Nie oznacza pełnego testu wszystkich pinów, peryferiów ani zgodności profilu Saola z każdą płytką S2. Poniższa instrukcja porządkuje tę procedurę; nie przedstawia nowego testu sprzętowego.

Archiwalny wybór obrazu BIN dla Saola 1 w/WROOM na stronie CircuitPython

Zrzut archiwalny z materiałów IMZ. Numery wersji na obrazku nie są zaleceniem instalowania starej bety. Aktualny obraz dobierz na stronie swojej płytki.

Wybierz płytkę i właściwe gniazdo

Potrzebujesz płytki ESP32-S2 obsługiwanej przez CircuitPython, przewodu USB do danych i komputera. Przed zmianą firmware zachowaj własny program oraz pliki konfiguracyjne — zapis nowego obrazu zastępuje dotychczasowe oprogramowanie.

Odszukaj dokładny model w katalogu obsługiwanych płytek CircuitPython. Sprawdź nazwę modułu, Flash, PSRAM i rewizję. Zbliżony wygląd PCB nie wystarcza. Wybrany profil definiuje również nazwy pinów board.*, wbudowaną diodę i dostępne funkcje.

Ważny przykład: oryginalna Saola 1 ma gniazdo micro USB podłączone do CP210x, a nie do natywnego USB ESP32-S2. Natywne linie to GPIO19/D− i GPIO20/D+. Dlatego zapis firmware przez konwerter może się udać, choć na tym samym gnieździe nie pojawi się dysk USB CircuitPython. Ta różnica jest opisana na oficjalnej stronie profilu Saola 1 w/WROOM.

Na płytce z gotowym gniazdem natywnego USB używaj właśnie tego złącza. Dorabianie USB do Saoli wymaga poprawnego połączenia linii danych, masy i toru zasilania zgodnie z dokumentacją; nie jest konieczne na płytkach, które już mają takie gniazdo. Samo wybranie firmware Saola nie zmienia fizycznych połączeń innej konstrukcji.

BIN, UF2 i dwa różne tryby startu

Element Do czego służy
Bootloader ROM ESP32-S2 Fabryczny mechanizm wgrywania programu, dostępny po BOOT + RESET
Obraz .bin Plik zapisywany odpowiednim narzędziem do Flash
TinyUF2 Dodatkowy bootloader, który udostępnia dysk do kopiowania plików .uf2
Dysk CIRCUITPY System plików działającego CircuitPython, m.in. code.py i biblioteki

Pliku UF2 nie kopiuje się na CIRCUITPY jak zwykłego programu. Potrzebny jest tryb dysku bootloadera TinyUF2. Obraz BIN można wgrać przez bootloader ROM bez wcześniejszego TinyUF2. Dla CircuitPython 10 i nowszego na płytkach Espressif z 4 MB Flash ścieżka UF2 wymaga odpowiednio nowego TinyUF2, co najmniej 0.33.0. Szczegóły i ostrzeżenia o utracie danych są na stronie instalacji profilu.

Wgranie obrazu BIN

Pobierz stabilny obraz dla ustalonego modelu. W przykładzie przyjmujemy pełny obraz CircuitPython dla ESP32-S2, którego dokumentacja przewiduje zapis od adresu 0x0. To nie jest uniwersalny adres dla dowolnego firmware ESP32. Dla innych obrazów korzystaj z ich instrukcji.

Taką ścieżkę zapisu dla obsługiwanych płytek S2 pokazuje również instrukcja producenta WEMOS. Wybierz jednak obraz dla swojego modelu; profil Saola ze zrzutu nie zastępuje profilu WEMOS ani innej płytki.

  1. Zamknij monitor portu i inne aplikacje korzystające z płytki.
  2. Przytrzymaj BOOT, naciśnij i puść RESET, następnie puść BOOT.
  3. Sprawdź port powstały w trybie pobierania — np. /dev/ttyACM0, /dev/ttyUSB0 albo COM7.
  4. Uruchom esptool, podstawiając rzeczywistą ścieżkę i port.

Przykład dla esptool 5.x w Linuxie:

python -m esptool --chip esp32s2 --port /dev/ttyACM0 write-flash 0x0 circuitpython-dla-mojej-plytki.bin

circuitpython-dla-mojej-plytki.bin jest nazwą przykładową. Polecenie zapisuje pamięć i nadpisuje sektory zajęte przez obraz. Nie wykonuj go, dopóki nie potwierdzisz zgodności pliku i nie zachowasz potrzebnych danych. Składnię offset/plik oraz zachowanie zapisu opisuje dokumentacja esptool. Narzędzie można zainstalować według instrukcji Espressif.

Archiwalny zrzut IMZ używa esptool 4.8.1 i nazwy write_flash. W 5.x nazwy poleceń używają łączników. Po zapisie w starym narzędziu pojawił się komunikat, że układ wszedł w Download Mode przez GPIO0 i wymaga ręcznego resetu. Jeżeli poprzedzają go poprawny zapis i weryfikacja, taki komunikat dotyczy wyjścia z bootloadera, a nie automatycznie nieudanego zapisu. Puść BOOT i naciśnij RESET.

Pierwsze uruchomienie i REPL

Po restarcie wybierz port działającego interpretera — może mieć inny numer niż bootloader. Przy prawidłowo podłączonym natywnym USB i konfiguracji z włączonym dyskiem powinien pojawić się CIRCUITPY.

Otwórz konsolę szeregową. W Linuxie, jeśli masz zainstalowany screen, przykładowe połączenie to:

screen /dev/ttyACM0 115200

Wciśnij Ctrl+C, aby przerwać wykonywanie programu i wejść do REPL. Wpisz:

print("Witaj w IMZ!")
import board
dir(board)

Lista board pomaga poznać nazwy pinów dostępne w wybranym firmware. Nie zastępuje schematu płytki: błędny profil może udostępniać nazwy niepasujące do Twojego PCB. Ctrl+D wykonuje miękki restart interpretera. Dokumentacja REPL CircuitPython.

Pierwszy plik code.py

Na dysku CIRCUITPY zapisz plik tekstowy code.py:

import time

while True:
    print("IMZ: CircuitPython działa")
    time.sleep(1)

To próba bez przewodów i bez założenia, do którego GPIO podłączono diodę. Obserwuj konsolę. Zmiana tekstu i ponowny zapis pozwala sprawdzić automatyczne przeładowanie programu. Poczekaj, aż system zakończy zapis, zanim odłączysz USB. Tworzenie i zapisywanie kodu.

Gdy nie ma dysku lub konsoli

  • Esptool działa, a dysku brak: upewnij się, że korzystasz z natywnego USB, nie z konwertera CP210x.
  • Płytka pozostaje w bootloaderze: puść BOOT i wykonaj zwykły reset.
  • Błędy programu w konsoli: przerwij kod przez Ctrl+C i popraw code.py.
  • Brak portu: sprawdź kabel, uprawnienia, właściwe gniazdo i diagnostykę USB.
  • Nazwy GPIO lub LED nie pasują: wróć do wyboru profilu płytki zamiast przepisywać przypadkowy pinout.

Po tym etapie możesz dołożyć bibliotekę czujnika lub prostą obsługę GPIO. Zaczynaj od jednego peryferium i zachowuj działający code.py, aby łatwo oddzielić problem programu od połączeń sprzętowych.