CircuitPython pozwala pisać programy w Pythonie i uruchamiać je na mikrokontrolerze. Po instalacji płytka z natywnym USB pojawia się w komputerze jako dysk CIRCUITPY. Zapisujesz na nim plik code.py, a program uruchamia się automatycznie. Nie musisz kompilować i wgrywać całego szkicu po każdej zmianie.
Pokażę, jak wgrać CircuitPython na ESP32-S2, otworzyć konsolę i uruchomić pierwszy program. Najpierw trzeba dobrać firmware do swojej płytki i wybrać właściwe gniazdo USB. To dwa miejsca, w których najłatwiej utknąć.
Co będzie potrzebne?
- Płytka ESP32-S2 obsługiwana przez CircuitPython.
- Przewód USB umożliwiający przesyłanie danych.
- Komputer z Pythonem i narzędziem esptool do wgrania firmware.
- Edytor tekstu oraz program do obsługi konsoli szeregowej.
Jeśli na płytce masz już własny program lub pliki, zachowaj ich kopię. Instalacja CircuitPython zastąpi dotychczasowe oprogramowanie.
Wybierz firmware dla swojej płytki
Odszukaj model w katalogu płytek CircuitPython. Sprawdź nazwę modułu, pojemność Flash, obecność PSRAM i wersję płytki. Sam napis „ESP32-S2” nie wystarczy: firmware określa także nazwy pinów, obsługę wbudowanej diody i dostępne funkcje.
Podczas tego uruchomienia korzystałem z obrazu Saola 1 w/WROOM, w wersji 10.0.0-beta.3. Dla swojej płytki pobierz stabilne wydanie z jej strony — nie musisz szukać wersji widocznej na zrzucie.

Na stronie płytki wybierasz wersję CircuitPython i pobierasz plik firmware. W tej instrukcji korzystamy z obrazu BIN.
Które gniazdo USB wybrać?
USB może łączyć komputer bezpośrednio z ESP32-S2 albo przez konwerter USB–UART. Przez konwerter da się wgrać firmware, ale nie zobaczysz na nim dysku CIRCUITPY. Do tego potrzebne jest natywne USB mikrokontrolera.
Przykładowo oryginalna Saola 1 ma gniazdo micro USB połączone z konwerterem CP210x. Jej natywne linie USB to GPIO19 (D−) i GPIO20 (D+). Szczegóły znajdziesz na stronie Saola 1 w/WROOM.
Jeśli Twoja płytka ma osobne gniazdo natywnego USB, użyj go do pracy z CircuitPythonem. W przypadku Saoli podłączenie natywnego USB wymaga wykonania połączeń danych, masy i zasilania zgodnie z dokumentacją. Wybranie profilu Saola w programie nie zmienia sposobu podłączenia gniazda USB na płytce.
BIN, UF2 i dysk CIRCUITPY
Przy pobieraniu firmware spotkasz pliki BIN i UF2. Oba służą do instalacji, ale wgrywa się je inaczej.
| Element | Do czego służy |
|---|---|
| Bootloader ROM ESP32-S2 | Wbudowany tryb wgrywania programu, uruchamiany przyciskami BOOT i RESET |
Plik .bin |
Obraz firmware zapisywany do pamięci Flash, np. przez esptool |
| TinyUF2 | Dodatkowy bootloader udostępniający dysk do kopiowania plików .uf2 |
Dysk CIRCUITPY |
Miejsce na Twój program code.py i biblioteki, dostępne po uruchomieniu CircuitPython |
Pliku UF2 nie kopiujesz na dysk CIRCUITPY. Służy do tego osobny dysk bootloadera TinyUF2. Natomiast obraz BIN można wgrać przez fabryczny bootloader ROM, bez instalowania TinyUF2.
Jeśli wybierasz UF2: CircuitPython 10 i nowszy na płytkach Espressif z 4 MB Flash wymaga TinyUF2 w wersji co najmniej 0.33.0. Przed aktualizacją sprawdź instrukcję na stronie płytki. Dalej opisuję instalację pliku BIN.
Wgraj CircuitPython przez esptool
Zainstaluj esptool według instrukcji Espressif i pobierz obraz BIN dla swojej płytki.
Poniższe polecenie zapisuje pełny obraz CircuitPython dla ESP32-S2 od adresu 0x0. Taki sposób instalacji opisuje także instrukcja WEMOS. Adres zapisu sprawdzaj w instrukcji pobranego obrazu — 0x0 nie jest uniwersalnym ustawieniem dla każdego firmware ESP32.
- Zamknij monitor portu i inne programy korzystające z płytki.
- Przytrzymaj BOOT, naciśnij i puść RESET, a następnie puść BOOT.
- Sprawdź nazwę portu. W Linuxie może to być
/dev/ttyACM0lub/dev/ttyUSB0, a w Windows np.COM7. - Uruchom polecenie, wpisując swój port i nazwę pobranego pliku.
Przykład dla esptool 5.x w Linuxie:
python -m esptool --chip esp32s2 --port /dev/ttyACM0 write-flash 0x0 circuitpython-dla-mojej-plytki.bin
Zastąp circuitpython-dla-mojej-plytki.bin rzeczywistą nazwą pliku. Jeśli znajduje się w innym katalogu, podaj pełną ścieżkę. Opis polecenia znajdziesz w dokumentacji esptool.
Po wgraniu naciśnij RESET
Przy moim uruchomieniu esptool 4.8.1 zapisał i zweryfikował obraz, a następnie wyświetlił komunikat o konieczności ręcznego resetu. Płytka weszła w tryb pobierania przez GPIO0 i trzeba było z niego wyjść: puścić BOOT i nacisnąć RESET.
Jeżeli zapis i weryfikacja zakończyły się poprawnie, sam komunikat o ręcznym resecie nie oznacza nieudanego wgrania. Nie trzeba od razu powtarzać instalacji.
W esptool 4.x polecenie nazywało się write_flash, a w 5.x — write-flash. Jeśli korzystasz ze starszej wersji narzędzia, zwróć uwagę na tę różnicę.
Otwórz konsolę i sprawdź, czy działa
Po restarcie powinien pojawić się dysk CIRCUITPY, o ile korzystasz z natywnego USB i firmware ma włączoną tę funkcję. Numer portu szeregowego może się zmienić — wybierz port działającego CircuitPython, a nie zapamiętany port bootloadera.
Otwórz konsolę szeregową. W Linuxie możesz użyć programu screen, jeśli jest zainstalowany:
screen /dev/ttyACM0 115200
Naciśnij Ctrl+C, aby przerwać wykonywanie programu i przejść do REPL, czyli konsoli, w której wpisujesz polecenia Pythona i od razu widzisz ich wynik. Wpisz kolejno:
print("Witaj w IMZ!")
import board
dir(board)
Pierwsze polecenie wypisze powitanie. Dwa kolejne pokażą nazwy dostępne w module board, m.in. oznaczenia pinów dla wybranego profilu płytki. Porównuj je z jej dokumentacją, gdy podłączasz zewnętrzne elementy.
Skrót Ctrl+D wykonuje miękki restart interpretera. Więcej o pracy z konsolą przeczytasz w instrukcji REPL CircuitPython.
Zapisz pierwszy program w code.py
Na dysku CIRCUITPY utwórz plik tekstowy code.py i zapisz w nim:
import time
while True:
print("IMZ: CircuitPython działa")
time.sleep(1)
W konsoli co sekundę powinien pojawiać się napis IMZ: CircuitPython działa. Do tej próby wystarczy sama płytka — nie podłączasz diody ani dodatkowych przewodów.
Zmień tekst w cudzysłowie i ponownie zapisz plik. CircuitPython przeładuje program, a w konsoli zobaczysz nową wiadomość. Tak wygląda codzienna praca: edytujesz plik, zapisujesz i sprawdzasz efekt.
Przed odłączeniem USB poczekaj na zakończenie zapisu. Wskazówki dotyczące edytorów znajdziesz w poradniku tworzenia plików CircuitPython.
Gdy coś nie działa
- Esptool wgrywa program, ale nie ma dysku
CIRCUITPY: sprawdź, czy używasz natywnego USB, a nie gniazda konwertera CP210x. - Płytka nadal jest w trybie pobierania: puść BOOT i naciśnij RESET.
- Program wyświetla błąd w konsoli: naciśnij
Ctrl+C, przeczytaj komunikat i poprawcode.py. - Komputer nie widzi portu: sprawdź przewód, gniazdo i uprawnienia do portu. Pomocny będzie poradnik o USB, UART i trybie BOOT.
- Nazwy pinów nie zgadzają się z płytką: sprawdź, czy pobrałeś firmware dla właściwego modelu.
Kiedy pierwszy program już działa, możesz podłączyć czujnik lub spróbować sterowania GPIO. Zachowaj kopię działającego code.py i dodawaj po jednym elemencie — łatwiej wtedy znaleźć przyczynę błędu w programie lub połączeniach.

