ESPHome i Tasmota wystarczają do wielu domowych projektów bez pisania kodu, ale prędzej czy później może się przydać oprogramowanie, które robi dokładnie to, czego potrzebujesz, i nic więcej. Arduino IDE z rdzeniem Arduino przygotowanym przez Espressif (arduino-esp32) to najpopularniejszy sposób na napisanie takiego oprogramowania w C++. Poniżej przejdziesz od świeżej instalacji Arduino IDE 2 do ESP32, które łączy się z siecią Wi-Fi, ogłasza swoją nazwę w sieci lokalnej i odpowiada na żądania HTTP.

Wszystkie informacje pochodzą z dokumentacji arduino-esp32, poradników Arduino IDE 2 na docs.arduino.cc i z Arduino Help Center. W chwili pisania najnowsze wydanie arduino-esp32 ma numer 3.3.12 (wrzesień 2026).

Czego potrzebujesz

  • Arduino IDE 2 pobrane ze strony Arduino Software. W dokumentacji arduino-esp32 jako minimum podano Arduino IDE 1.8, ale nazwy menu w tym tekście pochodzą z wersji 2.
  • Płytkę rozwojową z ESP32 i kabel USB, który przesyła dane. Na stronie z rozwiązywaniem problemów arduino-esp32 jest uwaga, że niektóre kable służą tylko do ładowania.
  • Nazwę sieci Wi-Fi (SSID) i hasło. Oryginalny ESP32 i ESP32-C3 obsługują tylko Wi-Fi 2,4 GHz.

Krok 1: dodaj adres menedżera płytek Espressif

Płytek ESP32 nie ma w IDE od razu. Trzeba wskazać menedżerowi płytek, skąd ma je pobrać, czyli dodać adres indeksu pakietów:

  1. Otwórz ustawienia: File > Preferences w Windows i Linuksie, Arduino IDE > Settings w macOS.
  2. Na dole okna znajdź pole Additional boards manager URLs.
  3. Wklej adres stabilnych wydań:
https://espressif.github.io/arduino-esp32/package_esp32_index.json

Jeśli w polu są już inne adresy, kliknij przycisk po jego prawej stronie. Otworzy się okno, w którym każdy adres wpisuje się w osobnym wierszu. Kliknij OK w tym oknie i jeszcze raz OK w ustawieniach.

Espressif publikuje też indeks rozwojowy (package_esp32_dev_index.json) z wersjami przedpremierowymi. Do urządzenia, które ma działać bez niespodzianek, wybierz wersję stabilną.

Krok 2: zainstaluj platformę esp32

W Arduino IDE 2 menedżer płytek znajduje się w lewej kolumnie: kliknij ikonę płytki Arduino (to samo okno otworzysz przez Tools > Board > Boards Manager). Wpisz esp32 w polu wyszukiwania i kliknij INSTALL przy pakiecie esp32 od Espressif Systems. Po zakończeniu przy pakiecie pojawi się napis INSTALLED i numer wersji.

Pakiet zawiera kompilatory i narzędzia dla wszystkich odmian ESP32, więc pobieranie trochę trwa. W dokumentacji arduino-esp32 jest zalecenie, by po instalacji uruchomić IDE ponownie.

Krok 3: wybierz płytkę i port

Podłącz płytkę. Obok przycisków weryfikacji i wgrywania u góry okna jest lista rozwijana z wykrytymi płytkami. Płytki z ESP32 często nie są rozpoznawane automatycznie, więc wybierz z tej listy Select other board and port... albo skorzystaj z menu Tools > Board i Tools > Port.

Dla typowej płytki z oryginalnym układem ESP32 wybierz ESP32 Dev Module. Dla płytki z ESP32-C3 wybierz ESP32C3 Dev Module albo dokładną nazwę swojej płytki, jeśli jest na liście. Port to urządzenie szeregowe, które pojawia się po podłączeniu płytki: port COM w Windows, urządzenie /dev/tty... w Linuksie i macOS.

Jeśli żaden port się nie pojawia, na stronie z rozwiązywaniem problemów arduino-esp32 są takie wskazówki: sprawdź, czy jest zainstalowany sterownik do układu USB-UART na płytce, wymień kabel (może służyć tylko do ładowania), użyj innego portu USB (najlepiej bezpośrednio w komputerze, bez koncentratora), sprawdź zasilanie, a na końcu weź pod uwagę uszkodzenie płytki.

Dwa złącza USB

Nowsze odmiany ESP32 mogą mieć dwa złącza USB. Według strony z rozwiązywaniem problemów arduino-esp32:

  • Złącze UART prowadzi przez konwerter USB-UART i pojawia się w systemie pod nazwą producenta tego układu, na przykład „Silicon Labs CP210x UART Bridge”.
  • Złącze USB korzysta z wbudowanego USB układu i pojawia się jako urządzenie Espressif („Espressif USB JTAG/serial debug unit”).

Oryginalny ESP32 nie ma wbudowanego USB, więc płytki z nim mają tylko połączenie przez UART. Jeśli korzystasz z natywnego złącza USB, ustaw w menu Tools opcję USB CDC On Boot na Enabled (a w układach, które mają opcję USB Mode, wybierz „Hardware CDC and JTAG”). Inaczej dane z Serial.print() nie trafią do monitora portu szeregowego. Przy złączu UART ustaw USB CDC On Boot na Disabled.

Linux: brak uprawnień

W Linuksie wgrywanie może się kończyć błędem „Permission denied”, mimo że port jest wybrany. W poradniku o wgrywaniu szkiców do Arduino IDE 2 jest wyjaśnienie: urządzenie szeregowe należy do grupy dialout. Sprawdź to poleceniem ls -l /dev/ttyACM* (numer na końcu może być inny), dodaj swojego użytkownika do grupy, a potem wyloguj się i zaloguj ponownie:

sudo usermod -a -G dialout <username>

Krok 4: napisz szkic

Poniższy szkic powstał na podstawie przykładu HelloServer z biblioteki WebServer w repozytorium arduino-esp32. Łączy się z Wi-Fi, ustawia nazwę hosta, uruchamia mDNS i odpowiada na porcie 80:

#include <WiFi.h>
#include <WebServer.h>
#include <ESPmDNS.h>

const char *ssid = "your-ssid";
const char *password = "your-password";

WebServer server(80);

void handleRoot() {
  String body = "hello from esp32!\nuptime: ";
  body += String(millis() / 1000);
  body += " s\n";
  server.send(200, "text/plain", body);
}

void handleNotFound() {
  server.send(404, "text/plain", "not found\n");
}

void setup() {
  Serial.begin(115200);

  WiFi.setHostname("esp32-test");
  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());

  if (MDNS.begin("esp32-test")) {
    Serial.println("MDNS responder started");
  }

  server.on("/", handleRoot);
  server.onNotFound(handleNotFound);
  server.begin();
  Serial.println("HTTP server started");
}

void loop() {
  server.handleClient();
  delay(2);
}

Kilka ważnych szczegółów:

  • WiFi.setHostname() trzeba wywołać przed WiFi.mode() i WiFi.begin(), co jest wprost napisane w dokumentacji Wi-Fi API arduino-esp32. Nazwa hosta pojawia się na liście klientów w routerze i może mieć najwyżej 32 znaki.
  • server.handleClient() musi być wywoływane regularnie w loop(). Jeśli dodasz tam powolny kod, na przykład długie wywołania delay(), serwer WWW nie będzie odpowiadać w czasie oczekiwania.
  • Hasło do Wi-Fi jest zapisane w pliku źródłowym otwartym tekstem. Nie wysyłaj szkicu w tej postaci do publicznego repozytorium.

Krok 5: zweryfikuj, wgraj i otwórz monitor portu szeregowego

Dwa przyciski na lewym końcu paska narzędzi to Verify (znaczek wyboru), który tylko kompiluje kod, i Upload (strzałka), który kompiluje i wgrywa. Najpierw użyj Verify; błędy kompilacji pojawią się w konsoli na dole okna. Potem kliknij Upload. Po zakończeniu w prawym dolnym rogu wyświetli się powiadomienie.

Monitor portu szeregowego (Serial Monitor) otworzysz przyciskiem w prawym górnym rogu IDE. W wersji 2 otwiera się jako karta na dole okna, a nie w osobnym oknie. W jego ustawieniach wybierz prędkość 115200, taką samą jak w Serial.begin(). Naciśnij przycisk resetu na płytce (często oznaczony EN albo RST). Powinny się pojawić kropki, a potem adres IP.

Teraz otwórz http://<adres IP>/ w przeglądarce na komputerze w tej samej sieci. Jeśli system na komputerze obsługuje nazwy mDNS, zadziała też http://esp32-test.local/.

Gdy wgrywanie się nie udaje

Najczęstszy błąd to:

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

Żeby przyjąć nowe oprogramowanie przez port szeregowy, ESP32 musi uruchomić się w trybie pobierania, a do tego podczas resetu GPIO0 musi być w stanie niskim. Na większości płytek rozwojowych dzieje się to automatycznie, ale nie zawsze. Na stronie z rozwiązywaniem problemów arduino-esp32 są takie porady:

  • Przytrzymaj przycisk BOOT w chwili, gdy zaczyna się wgrywanie.
  • Użyj innego kabla i innego portu USB, unikaj koncentratorów i sprawdź zasilanie.
  • Odłącz wszystko, co jest podłączone do pinów TX i RX.
  • Jeśli płytka regularnie nie wchodzi w tryb pobierania, przylutuj kondensator 10 µF między RST a GND albo dodaj układ opóźniający reset opisany w ESP32 Hardware Design Guidelines.

Co dalej

Od tego miejsca możesz odczytywać czujniki za pomocą bibliotek Arduino, wysyłać odczyty przez MQTT z użyciem biblioteki klienta MQTT albo dodawać kolejne ścieżki przez server.on(). Aktualizacje przez sieć (OTA) czy portal konfiguracyjny to dodatkowy kod, który musisz napisać i zabezpieczyć sam. To jeden z powodów, dla których ESPHome jest rozsądnym wyborem dla urządzeń ze standardowymi czujnikami i przełącznikami. Droga przez Arduino opłaca się wtedy, gdy potrzebujesz działania, którego nie oferuje żadne gotowe oprogramowanie.