Pierwsze wgranie oprogramowania to najtrudniejszy moment w ESPHome. Potrzebujesz kabla USB, który przenosi dane, przeglądarki obsługującej port szeregowy i płytki, która da się wprowadzić w tryb programowania. Potem każdą zmianę można już wysłać bezprzewodowo. Pokazuję, jak zainstalować Device Builder, utworzyć pierwszą konfigurację, wgrać ją przez USB, połączyć płytkę z Wi-Fi i dodać urządzenie w Home Assistancie.

Czego potrzebujesz

  • Płytki z ESP32. Do pierwszego projektu najbezpieczniej wziąć klasyczne ESP32 (ESP32-WROOM i podobne) - ESPHome uznaje je za najlepiej wspierany układ. ESP32-S3, ESP32-C3 i ESP32-C6 też nadają się do nowych projektów; ESP8266 omijaj przy nowej budowie, chyba że masz już działającą płytkę.
  • Kabla USB z liniami danych, nie samego ładowania. Kable „tylko do ładowania” to częsta przyczyna, dla której wgrywanie w ogóle się nie zaczyna.
  • Komputera z Chrome, Edge albo Firefox (obsługa WebSerial), jeśli wgrywasz z poziomu przeglądarki.
  • Home Assistanta z aplikacją ESPHome Device Builder albo samego Device Buildera jako programu na komputerze albo kontenera Docker. YAML jest w obu przypadkach ten sam.

Zainstaluj ESPHome Device Builder

Najczęściej Device Builder działa obok Home Assistanta:

  1. W Home Assistancie wejdź w Ustawienia > Aplikacje > Zainstaluj aplikację (Settings > Apps > Install App).
  2. Znajdź ESPHome Device Builder, zainstaluj, uruchom i otwórz interfejs.
  3. Jeśli aplikacji nie ma na liście, otwórz menu z trzema kropkami, wybierz Repozytoria (Repositories), dodaj https://github.com/esphome/home-assistant-addon i sprawdź listę ponownie.

Możesz też zainstalować Device Builder na Windows, macOS albo Linuksie ze strony instalacji ESPHome albo uruchomić oficjalny obraz Dockera i otworzyć http://localhost:6052. Kompilacja na Home Assistant Green albo Raspberry Pi potrafi zająć kilka minut; Device Builder potrafi oddać kompilację innemu panelowi na szybszym komputerze w sieci, jeśli sparujesz je w ustawieniach.

Utwórz pierwszą konfigurację

Otwórz Device Builder. Przy pustej liście zaproponuje utworzenie urządzenia. Wybierz Nowa konfiguracja urządzenia (New Device Setup), chyba że masz już plik YAML do zaimportowania.

Kreator pyta o nazwę, platformę (ESP32) i dane sieci Wi-Fi. Podaj je od razu. Bez nich płytka nie wejdzie do sieci, Home Assistant jej nie wykryje, a późniejsze aktualizacje bezprzewodowe nie zadziałają. Device Builder zapisuje te dane w pliku secrets.yaml w katalogu konfiguracji ESPHome i odwołuje się do nich przez !secret w pliku urządzenia, więc hasła nie wklejasz do każdego YAML-a, który komuś pokażesz.

Na końcu masz minimalną konfigurację: Wi-Fi, dziennik, API Home Assistanta i aktualizacje OTA. Tyle wystarczy do pierwszego wgrania.

Typowy szkielet wygląda mniej więcej tak (nazwy i klucze sekretów będą takie, jakie zapisał kreator):

esphome:
  name: living-room-node

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Living-Room-Fallback"
    password: !secret ap_password

captive_portal:

logger:

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

Dokładne nazwy kluczy w secrets.yaml zależą od kreatora. Trzymaj secrets.yaml z dala od publicznych repozytoriów; Device Builder domyślnie pomija ten plik, gdy katalog konfiguracji jest repozytorium git.

Pierwsze wgranie przez USB

Pierwsza instalacja musi iść kablem USB. Bezprzewodowo da się wgrywać dopiero wtedy, gdy na układzie jest już ESPHome.

  1. Podłącz płytkę do komputera, który widzi port szeregowy. Jeśli Home Assistant i Device Builder działają na innej maszynie niż ta z USB, wybierz Zainstaluj > Podłącz do tego komputera (Install > Plug into this computer), żeby przeglądarka na laptopie otworzyła ESPHome Web i rozmawiała z płytką lokalnie.
  2. W Device Builderze kliknij Zainstaluj (Install) na karcie urządzenia i przejdź przez kolejne kroki. Do wgrywania z przeglądarki potrzebujesz WebSerial (Chrome, Edge albo Firefox).
  3. Gdy pojawi się pytanie, wybierz port szeregowy. Na Linuksie bywa to /dev/ttyUSB0 albo /dev/ttyACM0, na Windowsie numer COM w Menedżerze urządzeń.
  4. Poczekaj na koniec kompilacji i wgrywania. Płytka uruchomi się już z tą konfiguracją.

Jeśli przeglądarka zgłasza, że nie udało się zainicjować połączenia, odłącz płytkę, przytrzymaj przycisk BOOT, podłącz ją ponownie, wybierz port i trzymaj BOOT, aż przygotowanie się zacznie. Część płytek wymaga też krótkiego naciśnięcia RESET przy wciśniętym BOOT. Gdy port w ogóle się nie pojawia, spróbuj innego kabla, innego gniazda USB i sterowników układu USB-UART z płytki (CP210x, CH340 i podobne).

Możesz też pobrać plik oprogramowania z Device Buildera (Zainstaluj > Pobierz ręcznie / Install > Manual download) i wgrać go przez ESPHome Web albo programem esptool. Plik jest przetwarzany lokalnie; nic nie trafia do chmury.

Połącz się z Wi-Fi i otwórz dziennik

Po udanym wgraniu płytka powinna dołączyć do sieci, którą podałeś. W Device Builderze karta przełączy się na Online. Otwórz Dziennik (Logs): przez USB dostaniesz konsolę szeregową, a gdy urządzenie jest już w sieci - dziennik przez API.

Jeśli płytka zostaje offline, sprawdź, czy SSID i hasło w secrets.yaml należą do sieci 2,4 GHz, do której ESP32 może się podłączyć, czy płytka jest w zasięgu i czy pierwszy zapis na układzie w ogóle się udał (kabel tylko do ładowania często zostawia stary program). Przy ukrytym SSID włącz fast_connect w sekcji wifi:. Stały adres IP (manual_ip) pomaga, gdy mDNS źle działa między VLAN-ami.

Dodaj urządzenie w Home Assistancie

Gdy węzeł jest w Wi-Fi, Home Assistant zwykle wykrywa go sam, o ile mDNS działa w sieci. Zaakceptuj wykrycie w Ustawienia > Urządzenia oraz usługi (Settings > Devices & services).

Żeby dodać ręcznie: Dodaj integrację, wyszukaj ESPHome i podaj nazwę hosta albo adres IP. Urządzenie o nazwie living-room-node jest osiągalne jako living-room-node.local, gdy mDNS działa. Przy zaszyfrowanym API (domyślnie w obecnych kreatorach) wklej klucz szyfrowania z Device Buildera (menu z trzema kropkami > Pokaż klucz API / Show API Key), gdy Home Assistant o niego poprosi.

Powtórz wykrywanie dla każdego nowego węzła ESPHome. Po pierwszym wgraniu przez USB kolejne zmiany wymagają tylko Zapisz, potem Zainstaluj; wybierz opcję bezprzewodową, żeby płytka mogła zostać tam, gdzie stoi.

Dodaj coś użytecznego, zanim skończysz

Sam węzeł z Wi-Fi wystarczy do sprawdzenia, że wgranie się udało, ale zwykle warto mieć choć jedną encję. W przewodniku startowym ESPHome pierwszym przykładem jest przełącznik GPIO:

switch:
  - platform: gpio
    name: "Desk Lamp"
    pin: GPIOXX

Zamień GPIOXX na pin podłączony do przekaźnika albo diody LED. Na wielu płytkach w stylu NodeMCU możesz użyć oznaczeń w rodzaju D1 zamiast numeru GPIO. Zapisz, wgraj bezprzewodowo, a przełącznik pojawi się w Home Assistancie bez dodatkowej konfiguracji po stronie serwera.

Unikaj pinów startowych (często GPIO0 i podobne) do wyjść, które przy starcie mogą zostać podciągnięte w złą stronę, chyba że znasz wymagania bootu danej płytki. ESPHome ostrzega o takich pinach w dzienniku kompilacji.

Typowe problemy przy pierwszym wgrywaniu

  • Brak portu albo „Failed to initialize”. Kabel tylko do ładowania, brak sterowników albo płytka poza trybem programowania. Przytrzymaj BOOT przy wyborze portu.
  • Kompilacja się udaje, Wi-Fi nie wstaje. Złe sekrety, sieć tylko na 5 GHz albo płytka nadal na fabrycznym oprogramowaniu, bo krok USB się nie skończył.
  • Komunikat „Brownout detector was triggered”. Napięcie 3,3 V spadło w trakcie nadawania Wi-Fi. Weź mocniejszy zasilacz 5 V, krótki gruby kabel USB, obniż wifi.output_power albo dodaj kondensator na linii 3,3 V, jak opisuje FAQ ESPHome.
  • Urządzenie online w Device Builderze, a Home Assistant go nie widzi. mDNS zablokowany między VLAN-ami albo Docker bez sieci hosta. Dodaj integrację ze stałym IP albo napraw routing multicastu.
  • Podkreślniki w nazwie hosta. W polu name: wolisz łączniki. Podkreślniki bywają problematyczne w DNS i u części routerów.

Co dalej

Przejrzyj katalog komponentów ESPHome pod kątem czujnika albo magistrali, którą masz na stole. Trzymaj jeden secrets.yaml na Wi-Fi, klucze API i hasła OTA, a Device Builder traktuj jako miejsce edycji YAML - samo zapisanie pliku nic nie zmienia na układzie, dopóki ponownie nie wgrasz oprogramowania.