Jak zainstalować ESPHome z Home Assistant — Kompletny przewodnik

ESPHome to otwartoźródłowy framework oprogramowania układowego, który pozwala przekształcić popularne mikrokontrolery — takie jak ESP32, ESP8266 i płytki RP2040 — w w pełni sterowalne urządzenia smart home.

„Konfiguracja” urządzenia w ESPHome składa się z jednego lub więcej plików YAML. Na podstawie tych plików ESPHome kompiluje niestandardowe oprogramowanie układowe, które możesz zainstalować bezpośrednio na swoim urządzeniu. Każdy sprzęt zdefiniowany w konfiguracji — czujniki, przełączniki, światła itp. — automatycznie pojawi się w interfejsie Home Assistant.

ESPHome składa się z dwóch głównych części:

1. Oprogramowanie układowe, które działa na Twoim mikrokontrolerze.

2. Narzędzie zarządzające, które działa na Twoim komputerze lub serwerze (np. Raspberry Pi, laptopie lub komputerze stacjonarnym) — w tym przewodniku użyjemy dodatku ESPHome Device Builder dla Home Assistant, który oferuje prosty interfejs webowy do tworzenia, edytowania i instalowania konfiguracji.

1. Instalacja dodatku ESPHome Device Builder

Najłatwiejszym sposobem na rozpoczęcie jest zainstalowanie ESPHome jako dodatku do Home Assistant.

Kroki:

1. W Home Assistant przejdź do Ustawienia → Sklep z dodatkami.

2. Search for ESPHome and click Install.

3. Poczekaj na zakończenie instalacji (może to potrwać minutę lub dwie).

4. Kliknij Start, a następnie Otwórz Web UI, aby uruchomić Device Builder.

Uwaga: Jeśli Twoja instalacja Home Assistant nie obsługuje dodatków, możesz uruchomić ESPHome Device Builder osobno w Dockerze.

2. Tworzenie Twojej Pierwszej Konfiguracji

Gdy otworzysz interfejs Web UI po raz pierwszy, kreator konfiguracji poprowadzi Cię przez proces tworzenia pierwszej konfiguracji urządzenia.

Będziesz musiał:

• Wprowadź nazwę urządzenia (zalecane małe litery z myślnikami).

• Wybierz typ płytki (np. ESP32 DevKit v1).

• Podaj SSID i hasło Wi‑Fi, aby urządzenie mogło połączyć się z Twoją siecią po wgraniu oprogramowania.

Wskazówka: Pierwsza instalacja na nowym urządzeniu jest często najbardziej stresującym krokiem. Jeśli nigdy tego nie robiłeś, sprawdź przewodnik Fizyczne połączenie z urządzeniem.

3. Pierwsze wgranie oprogramowania

Po utworzeniu konfiguracji musisz ją zainstalować na urządzeniu:

1. Podłącz swoją płytkę do hosta Home Assistant przez USB.

2. W ESPHome kliknij Zainstaluj i wybierz opcję USB.

3. Po wgraniu oprogramowania urządzenie połączy się z Twoim Wi‑Fi i będzie komunikować się z Home Assistant.

4. Eksploracja interfejsu Device Builder

Ekran główny ESPHome Device Builder wyświetla wszystkie Twoje konfiguracje urządzeń („węzły”). Dla każdej konfiguracji możesz:

• Zaktualizuj — jeśli wersja ESPHome urządzenia jest starsza niż wersja dodatku.

• Edytuj — otwórz edytor konfiguracji YAML.

• Logi — przeglądaj logi urządzenia przez USB/serial lub przez Wi‑Fi.

• Menu przepełnienia — dostęp do dodatkowych akcji:

  • Zweryfikuj — sprawdź konfigurację pod kątem błędów.

  • Zainstaluj — otwórz okno instalacji.

  • Wyczyść pliki kompilacji — usuń wygenerowane pliki kompilacji, aby naprawić problemy z kompilacją.

  • Usuń — usuń konfigurację.

Uwaga: Pliki konfiguracyjne są przechowywane w <HOME_ASSISTANT_CONFIG>/esphome/. Bezpośredni dostęp może wymagać dodatku SSH i wyłączenia „Trybu ochrony” — przed tym oceń konsekwencje bezpieczeństwa.

5. Dodawanie funkcjonalności do Twojego urządzenia

Przykład: Przełącznik GPIO

Otwórz plik YAML swojego urządzenia w edytorze i dodaj:

 
przełącznik:
  - platforma: gpio
    nazwa: "Osuszacz powietrza w salonie"
    pin: GPIO5
  

Tworzy to encję przełącznika w Home Assistant, która kontroluje wszystko, co jest podłączone do GPIO5 — może to być światło, wentylator lub inne urządzenie.

W powyższym przykładzie po prostu dodajemy przełącznik o nazwie „Osuszacz powietrza w salonie”, który jest podłączony do pinu GPIO5. Ten przełącznik może kontrolować dosłownie wszystko – na przykład światła lub wentylator stołowy. Jego nazwa i funkcja są dowolne i powinny być ustawione odpowiednio do Twojej konkretnej aplikacji.

Przykład: Czujnik binarny

Aby monitorować stan pinu GPIO (np. czujnik kontaktu okna), dodaj:

  - platforma: gpio
    nazwa: "Okno w salonie"
    pin:
      numer: GPIO0
      odwrócony: true
      tryb:
        input: true
        pullup: true
  

Po edycji kliknij Zapisz, aby zachować zmiany.

6. Aktualizacja urządzenia

Zapisanie pliku YAML nie aktualizuje automatycznie urządzenia. Za każdym razem, gdy wprowadzasz zmiany:

1. Kliknij Zainstaluj, aby ponownie skompilować oprogramowanie.

2. Zainstaluj je ponownie na urządzeniu.

Jeśli ESPHome jest już zainstalowany na urządzeniu, możesz je zaktualizować bezprzewodowo (OTA) bez ponownego podłączania USB.

7. Podłączanie urządzenia do Home Assistant

 DODAJ INTEGRACJĘ DO MOJEGO

Gdy urządzenie jest wgrane i połączone z Wi‑Fi:

• Home Assistant powinien automatycznie je wykryć (jeśli Twoja sieć obsługuje mDNS).

• Jeśli nie, przejdź do Ustawienia → Urządzenia i usługi → Dodaj integrację, wyszukaj ESPHome i wpisz nazwę hosta urządzenia (np. living-room-lamp.local) lub adres IP.

Powtórz ten proces dla każdego dodawanego urządzenia ESPHome.

8. Dokąd iść dalej

🎉 Gratulacje — skonfigurowałeś swój pierwszy projekt ESPHome i zainstalowałeś niestandardowe oprogramowanie na swoim urządzeniu! Nauczyłeś się także, jak dodawać podstawowe komponenty za pomocą YAML.

Następne kroki:

• Przeglądaj  Indeks komponentów aby znaleźć całe obsługiwane sprzęty.

• Sprawdź FAQ dla najczęstszych pytań.

• Jeśli napotkasz problemy lub chcesz zgłosić funkcje, otwórz zgłoszenie na  GitHub issue tracker.