ESPHome – jak zacząć, tworzyć konfiguracje i integrować urządzenia z Home Assistant?

ESPHome to rewolucyjna platforma, która upraszcza budowę i programowanie urządzeń IoT w domu.

Czy marzysz o własnym czujniku temperatury, wilgotności lub inteligentnym przełączniku? ESPHome czyni to możliwe nawet bez zaawansowanej wiedzy programistycznej. W tym poradniku krok po kroku zainstalujesz ESPHome, przygotujesz pierwszą konfigurację i bezproblemowo zintegrujesz urządzenia z Home Assistant.

Czym jest ESPHome?

ESPHome to nie tylko integracja do Home Assistant – to pełnoprawny framework, który znacząco upraszcza programowanie popularnych mikrokontrolerów, takich jak:

• ESP8266 – tani, popularny, idealna opcja dla początkujących;
• ESP32 – bardziej zaawansowany, z większą mocą obliczeniową;
• Raspberry Pi Pico W – nowsza alternatywa dla entuzjastów.

Największą zaletą ESPHome jest fakt, że nie wymaga pisania skomplikowanego kodu w C++ – zamiast tego używasz prostych plików YAML. To przełomowe podejście do tworzenia smart home’ów.

Główne zalety ESPHome

Poniżej znajdziesz kluczowe atuty ESPHome, które docenisz już po pierwszej konfiguracji:

• Bezpłatny i open-source – pełna kontrola nad kodem i przejrzysty rozwój społecznościowy;
• Prosta konfiguracja – szybki start nawet bez doświadczenia programistycznego;
• Bogata biblioteka modułów – gotowe integracje dla sensorów, przekaźników, wyświetlaczy i więcej;
• Szybka integracja z Home Assistant – urządzenia pojawiają się automatycznie w ekosystemie;
• Wsparcie dla Google Home – łatwe rozszerzenie sterowania głosowego i scen;
• Aktywna społeczność – setki poradników, przykładów i szybkiej pomocy.

Wymagania wstępne

Przed startem przygotuj niezbędne elementy:

1. Home Assistant – serwer z zainstalowanym HA (np. na Raspberry Pi lub osobnym komputerze);
2. Mikrokontroler – ESP8266 lub ESP32 (kupisz online za ok. 15–30 zł);
3. Kabel USB – do podłączenia płytki do komputera;
4. Dostęp do Wi‑Fi – urządzenie będzie w sieci 2.4 GHz;
5. Przewody i komponenty – zależnie od projektowanych czujników (opcjonalnie).

Krok 1 – instalacja ESPHome w Home Assistant

Etap 1 – dostęp do sklepu dodatków

Wykonaj poniższe czynności, aby otworzyć Sklep dodatków:

1. Otwórz Home Assistant na swoim serwerze.
2. Przejdź do Ustawienia (Settings) → Dodatki (Add‑ons).
3. Kliknij Sklep z dodatkami (Add‑on Store) w prawym górnym rogu.
4. Wyszukaj frazę ESPHome.

Etap 2 – instalacja i uruchomienie

Po znalezieniu dodatku zainstaluj go i uruchom:

1. Wybierz ESPHome z listy wyników.
2. Kliknij Zainstaluj (Install).
3. Poczekaj, aż instalacja się zakończy (zwykle 1–3 minuty).
4. Po instalacji kliknij Uruchom (Start).

Etap 3 – konfiguracja początkowa

Dla wygody zaznacz opcje: Pokaż na pasku bocznym oraz Uruchom przy starcie – ułatwi Ci to szybki dostęp do ESPHome po każdym restarcie.

Po uruchomieniu zobaczysz pulpit ESPHome z opcją dodania pierwszego urządzenia.

Krok 2 – przygotowanie sprzętu

Wybór płytki

Poniższa tabela pomoże Ci szybko porównać najpopularniejsze opcje i dobrać płytkę do projektu:

Płytka	Orientacyjna cena	Zużycie energii	Bluetooth	Najczęstsze zastosowania
ESP8266	15–25 zł	Niskie	Nie	Czujniki, przełączniki, proste automatyzacje
ESP32	30–50 zł	Wyższe	Tak	Projekty wymagające większej mocy, BLE, rozbudowane scenariusze

Popularne modele to m.in. Wemos D1 Mini i NodeMCU (ESP8266) oraz różne ESP32 DevKit.

Podłączenie płytki do komputera

Aby wgrać oprogramowanie po raz pierwszy, podłącz płytkę przewodem USB i sprawdź port:

1. Weź płytkę ESP8266/ESP32.
2. Podłącz ją do komputera kablem micro‑USB.
3. Upewnij się, że system rozpoznaje port (np. COM3/COM4 w Windows lub /dev/ttyUSB0 w Linux).

Krok 3 – tworzenie konfiguracji – pierwszy projekt

Uruchomienie kreatora nowego urządzenia

Otwórz ESPHome i skorzystaj z kreatora, aby wygenerować bazową konfigurację:

1. Przejdź do ESPHome (z paska bocznego lub przez Ustawienia).
2. Kliknij New Device (Nowe urządzenie).
3. Kreator pokaże trzy tryby pracy:

• New Device Setup – najlepszy dla początkujących;
• Import from File – wgranie istniejącej konfiguracji;
• Empty Configuration – czysty plik dla zaawansowanych.

Następujące kroki w kreatorze

Krok 1: Dane urządzenia – nadaj unikalną, opisową nazwę, np. „czujnik‑temperatury‑salon” lub „glosnik‑sypialnia”.

Krok 2: Wybór platformy – wskaż rodzinę (ESP8266, ESP32) i konkretny model płytki (np. „Wemos D1 Mini”, „ESP32 DevKit”).

Krok 3: Konfiguracja Wi‑Fi – wpisz SSID oraz hasło; dane zostaną zapisane w urządzeniu podczas pierwszego flashowania.

Krok 4: Przegląd – sprawdź podsumowanie i kliknij Utwórz (Create), aby zapisać plik YAML.

ESPHome automatycznie wygeneruje plik konfiguracyjny w formacie YAML, gotowy do kompilacji.

Krok 4 – wgrywanie oprogramowania na urządzenie

Instalacja oprogramowania – pierwszy raz

Podczas pierwszej instalacji użyj połączenia USB i wybierz odpowiedni port:

1. Upewnij się, że płytka jest podłączona do komputera przez USB.
2. W ESPHome Dashboard kliknij trzy kropki (…) obok nazwy urządzenia.
3. Wybierz Plug into the computer running ESPHome Dashboard.
4. Wskaż właściwy port USB.
5. ESPHome automatycznie wykona następujące czynności:

• pobierze potrzebne biblioteki,
• skompiluje kod,
• wgra oprogramowanie na urządzenie.

Proces trwa zwykle 2–5 minut. Po zakończeniu zobaczysz potwierdzenie.

Instalacja kolejnych urządzeń

Po pierwszym flashowaniu następne aktualizacje prześlesz bezprzewodowo:

1. Kliknij ikonę Upload (strzałka do góry) w ESPHome Dashboard.
2. ESPHome wyśle aktualizację przez Wi‑Fi bez użycia kabla.

Krok 5 – konfigurowanie komponentów – praktyczne przykłady

ESPHome posiada obszerną bibliotekę modułów do łatwego podłączania czujników, wyświetlaczy i aktuatorów. Poniżej znajdziesz gotowe fragmenty YAML:

Przykład 1 – czujnik temperatury DHT22

Poniżej przykładowa konfiguracja czujnika DHT22 dla temperatury i wilgotności:

esphome:
name: czujnik-temperatury
platform: ESP8266
board: d1_mini

wifi:
ssid: "Twoja_Siec_WiFi"
password: "Twoje_Haslo"

sensor:
- platform: dht
pin: D4
temperature:
name: "Temperatura salonu"
humidity:
name: "Wilgotność salonu"
update_interval: 60s

logger:

Przykład 2 – wyświetlacz OLED SSD1306

Tak skonfigurujesz magistralę I2C i wyświetlisz dane na ekranie OLED:

i2c:
sda: D2
scl: D1

display:
- platform: ssd1306_i2c
model: "SSD1306 128x64"
address: 0x3C
lambda: |-
it.printf(0, 0, id(font), "Temperature: %.1f°C", id(temp_sensor).state);
it.printf(0, 20, id(font), "Humidity: %.1f%%", id(humidity_sensor).state);

font:
- file: "gfonts://Roboto"
id: font
size: 14

Przykład 3 – przełącznik relay (przekaźnik)

Poniższy fragment tworzy prosty przełącznik GPIO do sterowania lampą:

switch:
- platform: gpio
pin: D8
name: "Lampa salonu"
id: lampa_salon


Gdzie znaleźć więcej modułów?

Pełną listę komponentów znajdziesz w oficjalnej dokumentacji https://esphome.io/. Przykładowe kategorie:

• sensory: temperatura, wilgotność, CO2, światło,
• aktuatory: przekaźniki, silniki,
• wyświetlacze: oled, lcd, e‑ink,
• komunikacja: i2c, spi, onewire.

Krok 6 – zarządzanie sekretami (passwords)

Dlaczego plik secrets?

Zamiast wpisywać hasło do Wi‑Fi w każdej konfiguracji, utwórz plik secrets.yaml. To wygodne i bezpieczne rozwiązanie, które ułatwia utrzymanie konfiguracji.

Jak utworzyć plik secrets?

Wykonaj te kroki, aby centralnie przechowywać wrażliwe dane:

1. W ESPHome Dashboard kliknij Secrets (ikona klucza).
2. Dodaj swoje dane w pliku secrets.yaml w następującej formie:

wifi_ssid: "Twoja_Siec"
wifi_password: "Twoje_Haslo"


1. Użyj sekretów w konfiguracji urządzenia zgodnie z poniższym wzorcem:

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


Krok 7 – integracja z Home Assistant

Automatyczne dodawanie urządzeń

Gdy urządzenie ESPHome połączy się z Wi‑Fi, Home Assistant automatycznie je wykryje i wyświetli powiadomienie o nowym urządzeniu.

Manualne dodawanie (jeśli wykrywanie nie zadziała)

Jeśli automatyczna detekcja nie wystąpi, dodaj integrację ręcznie:

1. Przejdź do Ustawienia → Urządzenia i Usługi (Devices & Services).
2. Kliknij Utwórz integrację (Create Integration).
3. Wyszukaj ESPHome.
4. Podaj adres IP urządzenia (sprawdzisz w routerze lub w ESPHome Dashboard).

Kontrola urządzenia z dashboardu

Po dodaniu urządzenia możesz wykonywać następujące czynności:

• odczytywać wartości – temperatura, wilgotność, stan czujników,
• sterować przełącznikami – włączać/wyłączać lampy i przekaźniki,
• tworzyć automatyzacje – np. „jeśli temperatura > 25°C, włącz klimatyzację”,
• korzystać z aplikacji mobilnej – pełen dostęp z telefonu.

Krok 8 – zaawansowane konfiguracje

Automatyzacja i logika

ESPHome pozwala wdrażać logikę bezpośrednio na urządzeniu, bez osobnych automatyzacji w HA. Przykład:

switch:
- platform: gpio
pin: D8
name: "Lampa salonu"
id: lampa_salon
on_turn_on:
- logger.log: "Lampa się włączyła!"

sensor:
- platform: dht
temperature:
name: "Temperatura"
id: temp_sensor
on_value:
if:
condition:
lambda: 'return x > 28;'
then:
- switch.turn_on: klimatyzacja

time:
- platform: homeassistant
id: homeassistant_time

automation:
- trigger:
platform: time
at: "22:00:00"
action:
- switch.turn_off: lampa_salon

Niestandardowe skrypty

Jeśli znasz C++, możesz skorzystać z niestandardowych lambd, by wykonywać własne obliczenia:

sensor:
- platform: template
name: "Obliczenia custom"
lambda: |-
if (id(czujnik1).state > 20 && id(czujnik2).state < 50) {
return 100.0;
}
return 0.0;


Rozwiązywanie problemów

Problem 1 – urządzenie nie łączy się z Wi‑Fi

Przyczyny i rozwiązania – sprawdź najczęstsze powody i działaj według poniższych wskazówek:

• sprawdź poprawność ssid i hasła w konfiguracji,
• upewnij się, że router nadaje w paśmie 2.4 GHz (ESP8266 nie obsługuje 5 GHz),
• zweryfikuj siłę sygnału Wi‑Fi w miejscu instalacji urządzenia,
• wgraj ponownie konfigurację i zrestartuj moduł.

Problem 2 – ESPHome Dashboard nie widzi urządzenia

Rozwiązania – wykonaj kolejno poniższe kroki:

• przejdź do ESPHome → Logs i sprawdź komunikaty błędów,
• skontroluj przewód i połączenie USB,
• upewnij się, że sterownik USB jest zainstalowany,
• uruchom ponownie ESPHome lub cały serwer.

Problem 3 – wgrywanie zawiesza się

Próby naprawy – zastosuj jedną z metod:

• odłącz i ponownie podłącz urządzenie,
• użyj innego portu USB lub przewodu,
• wgraj z opcją Erase Flash (wymazanie pamięci),
• zaktualizuj ESPHome do najnowszej wersji.

Dobre praktyki

1. Konfiguruj secrets od początku

Centralne przechowywanie haseł oszczędza czas i zwiększa bezpieczeństwo, zwłaszcza gdy dodajesz kolejne urządzenia.

2. Używaj opisowych nazw

Stosuj jasne i czytelne nazwy encji – unikniesz chaosu w dashboardach i automatyzacjach:

# Dobrze
- platform: dht
temperature:
name: "Temperatura salonu"

# Źle
- platform: dht
temperature:
name: "Temp"

3. Testuj komponenty indywidualnie

Dodawaj po jednym czujniku i sprawdzaj działanie, zanim rozszerzysz projekt o kolejne elementy.

4. Dokumentuj swoje projekty

Przechowuj kopie plików YAML poza Home Assistant (pendrive, chmura), aby łatwo odtworzyć konfiguracje.

5. Regularnie aktualizuj ESPHome

Aktualizacje przynoszą poprawki bezpieczeństwa oraz nowe funkcje, które często ułatwiają codzienne użytkowanie.

Zaawansowane integracje

Integracja z Google Home

Jeśli masz Home Assistant spięty z Google Home, urządzenia ESPHome pojawią się automatycznie. Dzięki temu możesz:

• sterować urządzeniami głosem,
• tworzyć sceny i automatyzacje,
• monitorować stany czujników w aplikacji Google Home.

Integracja z Node‑RED

Po instalacji Node‑RED w Home Assistant zbudujesz zaawansowane przepływy automatyzacji wizualnie, wykorzystując dane z ESPHome.

Tworzenie pulpitów nawigacyjnych (dashboard)

Home Assistant umożliwia tworzenie estetycznych dashboardów dla czujników ESPHome używając Lovelace UI lub Mushroom Cards.

Przykładowe projekty

Projekt 1 – multisensor pokojowy

Elementy, które warto połączyć w jednym urządzeniu:

• czujnik temperatury i wilgotności (DHT22),
• czujnik jakości powietrza (MQ135 lub SCD30),
• wyświetlacz OLED,
• przycisk fizyczny do kontroli.

Koszt: 50–80 zł | Czas: 2–3 godziny

Projekt 2 – inteligentne oświetlenie

Podstawowy zestaw do automatyzacji światła:

• przełącznik Wi‑Fi (relay),
• czujnik światła (BH1750),
• czujnik ruchu (PIR),
• logika automatycznego włączania/wyłączania.

Koszt: 30–50 zł | Czas: 1–2 godziny

Projekt 3 – stacja pogodowa

Propozycja zestawu do monitoringu warunków zewnętrznych:

• czujnik temperatury,
• barometr (BME280),
• pomiar UV (ML8511),
• wyświetlacz e‑ink.

Koszt: 80–120 zł | Czas: 4–6 godzin

Zasoby i linki

Przydatne źródła, z których warto korzystać na bieżąco:

• Oficjalna strona ESPHome – https://esphome.io/;
• Dokumentacja Home Assistant – https://www.home-assistant.io/;
• Forum ArturHome (Polska społeczność) – https://forum.arturhome.pl/;
• YouTube – kanały dedykowane – szukaj „ESPHome tutorial PL”.