Wstęp do ESPHome

/ bez kategorii, naukowo / Przez

Mój prompt do Gemini 3.5 flash: Napisz w formie ewentualnej notki na blogu, na czym polega programowanie ESPHome i jak można go wykorzystać do własnego systemu inteligentnego domu opartego na serwerze MQTT (raspberry Pi Zero 2W Mosquitto) i czujnikach na ESP32-C3-super-mini.

ESPHome i MQTT: Jak ożywić ESP32-C3 Super Mini bez linijki kodu w C++?

Jeśli bawisz się w IoT i inteligentny dom, na pewno znasz ten ból: pisanie obsługi Wi-Fi, walka z bibliotekami do czujników, ręczne kodowanie ponownego łączenia z brokerem MQTT po zerwaniu sygnału… i nagle prosty projekt pochłania dwa wieczory debugowania w Arduino IDE czy MicroPythonie.

A gdyby tak dało się to zrobić prościej, szybciej i bez pisania kodu w C++? Tutaj na scenę wkracza ESPHome. Sprawdźmy, jak ten system redefiniuje tworzenie własnych czujników i jak łatwo spiąć go z serwerem MQTT postawionym na miniaturowym Raspberry Pi Zero 2 W.

Czym właściwie jest ESPHome?

W dużym skrócie: ESPHome to system, który pozwala tworzyć niestandardowe oprogramowanie dla układów ESP8266 i ESP32 za pomocą prostych plików konfiguracyjnych YAML.

Zamiast pisać kod, opisujesz swoje urządzenie w sposób deklaratywny. Mówisz systemowi: „Mam ESP32-C3, do pinu GPIO8 jest podpięty czujnik temperatury, a dane chcę wysyłać na mój serwer MQTT”. ESPHome bierze ten plik YAML, sam generuje optymalny kod w C++, kompiluje go i wgrywa na Twój mikrokontroler.

Dlaczego to genialne rozwiązanie?

  • Zero C++: Nie musisz martwić się zarządzaniem pamięcią czy przerwaniami.
  • Wbudowana stabilność: ESPHome ma świetne mechanizmy automatycznego wznawiania połączeń Wi-Fi i MQTT.
  • Aktualizacje OTA (Over-The-Air): Pierwszy raz wgrywasz soft po kablu USB, a każdą kolejną zmianę przesyłasz bezprzewodowo.
  • Ogromna baza wspieranego sprzętu: Obsługa setek czujników, wyświetlaczy (e-papier, OLED), diod LED i przekaźników jest gotowa „out-of-the-box”.

Architektura systemu: Pi Zero 2 W + Mosquitto + ESP32-C3

Nasz system budujemy na trzech niezwykle mocnych, a zarazem miniaturowych filarach:

  1. Mózg i Serce (Raspberry Pi Zero 2 W): Ta malutka malina pobiera znikome ilości prądu, a ma wystarczająco dużo mocy, by udźwignąć system operacyjny i brokera wiadomości.
  2. Kurier (Mosquitto MQTT): Zainstalowany na Pi Zero broker działa jako centralny punkt wymiany informacji. Czujniki publikują tu swoje odczyty, a systemy sterowania (lub inne urządzenia) je odbierają.
  3. Zwiadowca (ESP32-C3 Super Mini): Płytka o wymiarach niewiele większych od znaczka pocztowego. Kosztuje grosze, ma wbudowane Wi-Fi, Bluetooth oraz świetną wydajność. Idealna do ukrycia w małej obudowie z czujnikiem.

Programowanie ESP32-C3 w ESPHome krok po kroku

Aby to wszystko zadziałało, potrzebujesz zainstalowanego ESPHome (np. na swoim komputerze PC/Mac lub bezpośrednio na Raspberry Pi). Instalacja sprowadza się do jednej komendy w Pythonie: pip install esphome.

Gdy masz już ESPHome, tworzenie softu dla ESP32-C3 Super Mini to czysta przyjemność. Cała magia zamyka się w jednym pliku konfiguracyjnym (np. salon-czujnik.yaml).

Oto jak wygląda przykładowy, w pełni funkcjonalny plik konfiguracyjny, który łączy się z Wi-Fi, brokerem Mosquitto i wysyła stan wbudowanej niebieskiej diody LED oraz odczyt z czujnika temperatury:

YAML

esphome:
  name: salon-czujnik
  friendly_name: Czujnik w Salonie

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf

# Konfiguracja połączenia Wi-Fi
wifi:
  ssid: "Nazwa_Twojej_Sieci_WiFi"
  password: "Haslo_Do_Twojej_Sieci"

  # Awaryjny punkt dostępowy, gdyby domowe Wi-Fi padło
  ap:
    ssid: "Salon-Czujnik-Fallback"

# Integracja z brokerem MQTT na Raspberry Pi Zero 2 W
mqtt:
  broker: 192.168.1.15  # Adres IP Twojego Raspberry Pi
  port: 1883
  username: "twój_użytkownik_mqtt"
  password: "twoje_hasło_mqtt"
  topic_prefix: dom/salon

# Logowanie zdarzeń (przydatne do debugowania przez USB lub sieciowo)
logger:

# Przykład definicji fizycznych komponentów
status_led:
  pin:
    number: GPIO8
    inverted: true

sensor:
  # Przykład: Odczyt wewnętrznej temperatury samego układu ESP32-C3
  - platform: internal_temperature
    name: "Temperatura ESP32-C3"
    update_interval: 60s

Jak to uruchomić?

  1. Podłączasz ESP32-C3 Super Mini kablem USB do komputera.
  2. Uruchamiasz w terminalu komendę kompilacji i wdrożenia: Bash esphome run salon-czujnik.yaml
  3. ESPHome automatycznie pobierze niezbędne narzędzia, skompiluje kod i wgra go na płytkę.
  4. Od tej pory, przy każdej zmianie w pliku YAML, nie musisz już podpinać kabla! ESPHome wykryje urządzenie w sieci lokalnej i zaktualizuje je bezprzewodowo (OTA).

Jak to wygląda w praktyce po stronie MQTT?

Gdy ESP32-C3 się uruchomi, automatycznie połączy się z brokerem Mosquitto na Raspberry Pi i zacznie publikować dane. Na dowolnym urządzeniu w sieci (lub na samym Pi Zero) możesz podsłuchać te wiadomości za pomocą narzędzia mosquitto_sub:

Bash

mosquitto_sub -h 192.168.1.15 -t "dom/salon/#" -v

W konsoli zobaczysz czysty, czytelny strumień danych:

Plaintext

dom/salon/sensor/temperatura_esp32-c3/state 42.5
dom/salon/status online

Dane te możesz teraz banalnie łatwo podpiąć pod dowolny system wizualizacji – od Node-RED, przez Home Assistant, aż po własny skrypt w Pythonie czy dashboard na stronie WWW.

💡 Szybka wskazówka dla projektantów: > Płytki ESP32-C3 Super Mini mają dość gęsto upakowane komponenty, przez co sam procesor potrafi się lekko nagrzewać. Jeśli używasz zewnętrznego czujnika temperatury (np. DHT22 czy DS18B20), wyprowadź go na kilkucentymetrowym przewodzie poza obudowę, aby ciepło z płytki nie zakłamywało odczytów!

Podsumowanie

Połączenie ESPHome + ESP32-C3 Super Mini + Raspberry Pi z Mosquitto to bezkonkurencyjny zestaw do budowy domowego IoT. Otrzymujesz stabilność profesjonalnego oprogramowania, elastyczność otwartego protokołu MQTT oraz miniaturowe rozmiary sprzętu – a wszystko to bez napisania choćby jednej linijki kodu w C++.

MÓJ PROMPT: Czy możemy na próbę wgrać proste mruganie diodą za pomocą ESPHome? Jak to zrobić korzystając z edytora Code na mac?

Jasne! Taki klasyczny „Hello World” w świecie IoT, czyli mruganie wbudowaną diodą, to najlepszy sposób, aby upewnić się, że cały Twój „łańcuch dostaw” (VS Code -> Mac -> ESP32-C3) działa bez zarzutu.

Płytka ESP32-C3 Super Mini ma wbudowaną niebieską diodę LED podłączoną do pinu GPIO8. Co ważne, działa ona w logice active-low (świeci, gdy stan pinu jest niski), dlatego w konfiguracji użyjemy parametru inverted: true.

Oto kompletna instrukcja, jak krok po kroku przygotować i wgrać ten projekt za pomocą edytora Visual Studio Code na Twoim Macu.

Krok 1: Przygotowanie Visual Studio Code na macOS

  1. Uruchom VS Code i otwórz w nim dowolny pusty folder na dysku (np. ESPHome-Projekty).
  2. Przejdź do zakładki Extensions (skrót Cmd + Shift + X) i wyszukaj oficjalne rozszerzenie ESPHome (stworzone przez Nabu Casa). Zainstaluj je.
    • Dlaczego warto? Zapewni Ci ono genialne podpowiadanie składni (autouzupełnianie) oraz od razu zaznaczy błędy w plikach YAML.
  3. Otwórz zintegrowany terminal w VS Code (Ctrl + ~ lub z menu górnego Terminal -> New Terminal).

Krok 2: Tworzenie pliku konfiguracyjnego YAML

W otwartym folderze utwórz nowy plik o nazwie mrugaj.yaml i wklej do niego poniższą konfigurację:

YAML

esphome:
  name: mrugaj-c3

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf

# ESPHome wymaga sekcji wifi, aby urządzenie nie wpadało w pętlę restartów (safe-mode).
# Wpisz tu dane swojej domowej sieci.
wifi:
  ssid: "Twoje_WiFi"
  password: "Twoje_Haslo"

# Konfiguracja wbudowanej diody jako przełącznika (Switch)
switch:
  - platform: gpio
    pin:
      number: GPIO8
      inverted: true  # Wbudowana dioda świeci przy stanie niskim (GND)
    id: niebieska_dioda
    name: "Wbudowana Dioda LED"

# Automatyzacja: mruganie co 1 sekundę
interval:
  - interval: 1s
    then:
      - switch.toggle: niebieska_dioda

Krok 3: Instalacja ESPHome w systemie (jeśli jeszcze jej nie masz)

W zintegrowanym terminalu VS Code upewnij się, że masz zainstalowane ESPHome. Najprościej zrobić to za pomocą Pythona, który w macOS jest zazwyczaj dostępny pod komendą python3:

Bash

pip3 install esphome

Krok 4: Pierwsze flashowanie przez USB

  1. Podłącz ESP32-C3 Super Mini kablem USB do portu w Macu.
    • Ważna uwaga: Użyj kabla, który na pewno przesyła dane (niektóre tanie kable od ładowarek mają tylko linie zasilania).
  2. Sprawdź, jak macOS nazwał port USB. Wpisz w terminalu VS Code:Bashls /dev/cu.* Szukaj pozycji wyglądającej podobnie do /dev/cu.usbmodemXXXX lub /dev/cu.wchusbserialXXXX. Nowoczesne systemy macOS posiadają już wbudowane sterowniki dla układów CH343/CH340 stosowanych w tych płytkach, więc system powinien wykryć ją od strzału.
  3. Uruchom proces kompilacji i wgrywania programu:Bashesphome run mrugaj.yaml

Co się teraz wydarzy?

  • ESPHome przeanalizuje plik YAML.
  • Przy pierwszym uruchomieniu pobierze kompilator oraz odpowiedni framework dla ESP32-C3 (może to zająć chwilę).
  • Narzędzie zapyta Cię, którego portu użyć do wgrania oprogramowania – wybierz z listy wykryty port /dev/cu.usbmodem....
  • Skompiluje kod do pliku binarnego i wgra go na płytkę.

Gdy proces dobiegnie końca, w terminalu automatycznie uruchomi się podgląd logów na żywo (Logger), a niebieska dioda na Twojej płytce ESP32-C3 Super Mini powinna zacząć miarowo mrugać co sekundę!

Aby wyjść z podglądu logów w terminalu, wciśnij Ctrl + C. Kolejne zmiany w pliku YAML możesz już wgrywać bezprzewodowo (OTA), wpisując tę samą komendę esphome run mrugaj.yaml – program sam wykryje działające w sieci lokalnej urządzenie.

Mój prompt: Wszystko przebiegło świetnie, dioda mruga, Mam takie info na konsoli:
INFO Successfully uploaded program.
ERROR Logger is not configured!
1. Jak to naprawić?
2. Proces trwał długo, zastanawiam się jak dużo miejsca na dysku głównym zabiera wgrywanie z pomocą ESPHome.
3. Czy warto użyć środowiska wirtualnego w tym wypadku?

ChatGPT: Gratulacje! Pierwszy sukces („Blink”) za Tobą. Skoro dioda mruga, to znaczy, że komunikacja Mac -> mikrokontroler działa perfekcyjnie, a Twój ESP32-C3 Super Mini jest w pełni sprawny.

Poniżej znajdziesz konkretne odpowiedzi na Twoje pytania i instrukcję, jak poukładać to środowisko w sposób w pełni profesjonalny i bezpieczny dla systemu macOS.

1. Skąd ten błąd: ERROR Logger is not configured!?

Komunikat ten pojawia się, ponieważ po poprawnym wgraniu oprogramowania (Successfully uploaded program), program kliencki ESPHome na Twoim Macu automatycznie próbuje przełączyć się w tryb nasłuchiwania logów przez port USB.

Jednak w pliku konfiguracyjnym mrugaj.yaml z poprzedniego kroku celowo pominęliśmy sekcję logera, aby kod był jak najkrótszy. W efekcie ESP32-C3 nie ma wgranych funkcji wysyłania logów i Twój Mac nie ma czego nasłuchiwać.

Jak to naprawić?

Wystarczy, że dodasz jedną linijkę do swojego pliku YAML (może być na samym dole lub pod sekcją esp32:):

YAML

logger:

Gdy teraz ponownie uruchomisz esphome run mrugaj.yaml, ESPHome skompiluje moduł diagnostyczny i po wgraniu softu zobaczysz w terminalu piękny, kolorowy strumień informacji na żywo o pracy Twojej płytki.

2. Dlaczego to trwało tak długo i ile miejsca na dysku zajmuje ESPHome?

Dlaczego pierwszy raz trwał tak długo?

To tzw. „zimny start” (cold build). Przy pierwszym uruchomieniu ESPHome musiał:

  1. Pobrać cały łańcuch narzędzi kompilacji (toolchain) dla architektury RISC-V (którą posiada ESP32-C3).
  2. Pobrać framework ESP-IDF lub Arduino.
  3. Skompilować od zera wszystkie biblioteki systemowe (obsługę Wi-Fi, systemu operacyjnego czasu rzeczywistego FreeRTOS itp.).

Dobra wiadomość: Każda kolejna kompilacja tego projektu na Twoim Macu mini M4 zajmie zaledwie kilka sekund! ESPHome korzysta z pamięci podręcznej i przy kolejnych wdrożeniach kompiluje wyłącznie te fragmenty kodu, które rzeczywiście uległy zmianie w pliku YAML.

Ile miejsca na dysku to zabiera?

Wszystkie narzędzia, biblioteki i pamięć podręczna kompilacji są domyślnie zapisywane w Twoim katalogu domowym na macOS:

  • Narzędzia PlatformIO: ~/.platformio
  • Pamięć podręczna ESPHome: ~/.esphome (oraz ukryty folder .esphome w katalogu Twojego projektu).

Bilans przestrzeni dyskowej:

  • Na start: Świeża instalacja z jednym ściągniętym frameworkiem i kompilatorem dla ESP32-C3 zajmuje około 1.5 GB do 2.5 GB.
  • Z czasem: Jeśli zaczniesz kompilować projekty dla różnych mikrokontrolerów (klasyczne ESP32, ESP8266, ESP32-S3) i będą się one aktualizować, katalog ~/.platformio potrafi po roku urosnąć nawet do 10–15 GB.

💡 Wskazówka: Jeśli kiedyś uznasz, że potrzebujesz odzyskać przestrzeń, możesz bez obaw usunąć foldery ~/.platformio oraz ~/.esphome. Przy kolejnym uruchomieniu ESPHome po prostu pobierze je na nowo (co znów chwilę potrwa, ale zwolni dysk „tu i teraz”).

3. Czy warto użyć środowiska wirtualnego (venv)?

Zdecydowanie TAK! W świecie Pythona na macOS używanie środowisk wirtualnych (venv) to obecnie najlepsza praktyka, a w nowszych wersjach systemu wręcz konieczność.

Dlaczego warto (a nawet trzeba)?

  1. Bezpieczeństwo systemu (PEP 668): Nowoczesny macOS blokuje instalację pakietów za pomocą globalnego pip install, aby chronić skrypty systemowe przed nadpisaniem przez zewnętrzne biblioteki. Próba instalacji globalnej często kończy się błędem externally-managed-environment.
  2. Porządek w systemie: ESPHome pociąga za sobą sporo zależności (np. biblioteki kryptograficzne, specyficzne wersje PlatformIO). Zamykając je w dedykowanym folderze, nie „śmiecisz” w systemie operacyjnym.
  3. Łatwe sprzątanie: Jeśli kiedyś postanowisz porzucić ESPHome, po prostu usuwasz folder środowiska wirtualnego i temat głowy.

Jak to poprawnie skonfigurować w VS Code na Macu?

Zróbmy to elegancko i profesjonalnie. Załóżmy, że Twój folder z projektami nazywa się ESPHome-Projekty.

  1. Otwórz ten folder w VS Code i wywołaj zintegrowany terminal.
  2. Stwórz środowisko wirtualne o nazwie .venv (kropka na początku sprawi, że folder będzie ukryty w finderze):Bashpython3 -m venv .venv
  3. Aktywuj środowisko wirtualne w terminalu:Bashsource .venv/bin/activate (Zauważysz, że na początku linii terminala pojawi się znacznik (.venv) – to znak, że pracujesz w odizolowanym środowisku).
  4. Zainstaluj ESPHome wewnątrz tego środowiska:Bashpip install esphome
  5. Powiedz o tym VS Code:
    • Wciśnij Cmd + Shift + P (Command Palette).
    • Wpisz i wybierz: Python: Select Interpreter.
    • VS Code powinien automatycznie wykryć środowisko z Twojego folderu (oznaczone jako '(.venv)': .venv/bin/python). Wybierz je.

Dzięki temu wbudowane w VS Code rozszerzenie ESPHome będzie korzystać z tej samej, czystej instalacji Pythona, a Ty zyskasz pełną kontrolę nad swoim środowiskiem programistycznym bez ryzyka uszkodzenia czegokolwiek w systemie macOS.

Mój prompt: Zrobiłem tak:
odinstalowałem ESPHome z ogólnego Pythona (pip3 uninstall esphome)
stworzyłem w poprzednim folderze .venv
aktywowałem .venv
zainstalowałem esphome w środowisku wirtualnym
Po komendzie (.venv) m4yar@YarMac4 ESPHome-blinking % esphome run mrugaj-OTA.yaml mam coś takiego:
WARNING: Failed to download https://github.com/Kitware/CMake/releases/download/v3.30.2/cmake-3.30.2-macos-universal.tar.gz to /Users/m4yar/Library/Caches/esphome/idf/dist/cmake-3.30.2-macos-universal.tar.gz.tmp
ERROR: Failed to download, and retry count has expired

To klasyczny i niezwykle częsty problem na systemach macOS!

Powód jest prosty: Python zainstalowany na Macu nie korzysta domyślnie z systemowych certyfikatów SSL (Keychain). Kiedy nowo zainstalowany ESPHome w środowisku wirtualnym próbuje pobrać kompilator CMake z GitHuba przez bezpieczne połączenie HTTPS, Python odrzuca to połączenie, ponieważ „nie zna” i nie potrafi zweryfikować certyfikatu SSL GitHuba.

Naprawmy to szybko. Wypróbuj poniższe kroki (najlepiej po kolei).

Krok 1: Aktualizacja certyfikatów wewnątrz Twojego .venv (Najszybsza metoda)

Upewnij się, że masz aktywne środowisko .venv w terminalu VS Code (powinieneś widzieć przedrostek (.venv)). Wpisz i uruchom poniższą komendę:

Bash

pip install --upgrade certifi

Ta komenda zainstaluje i zaktualizuje pakiet certifi, który dostarcza Pythonowi aktualną bazę zaufanych urzędów certyfikacji.

Krok 2: Uruchomienie skryptu instalacji certyfikatów macOS (Zalecane)

Jeśli instalowałeś Pythona pobierając go bezpośrednio z oficjalnej strony python.org, instalator zostawił na Twoim dysku specjalny skrypt, który automatycznie pobiera i konfiguruje certyfikaty dla danej wersji Pythona.

Możesz go wywołać bezpośrednio z terminala. Wpisz:

Bash

open "/Applications/Python 3.14/Install Certificates.command"

(Jeśli używasz innej wersji Pythona jako bazy, np. 3.13, zmień odpowiednio numer folderu w ścieżce).

Otworzy się nowe okno terminala, które automatycznie pobierze i zainstaluje najnowsze certyfikaty dla Twojego Pythona. Gdy proces się zakończy, możesz zamknąć to nowe okno.

Krok 3: Alternatywa dla użytkowników Homebrew (Jeśli powyższe nie pomogły)

Jeśli Twój Python pochodzi z menedżera pakietów Homebrew, problem może leżeć po stronie nieaktualnych certyfikatów w samym systemie macOS. Wtedy w terminalu (poza środowiskiem .venv) warto wpisać:

Bash

brew install ca-certificates

Co zrobić po wykonaniu tych kroków?

Gdy wykonasz Krok 1 oraz Krok 2, wróć do swojego terminala z aktywnym środowiskiem .venv w VS Code i ponownie uruchom proces:

Bash

esphome run mrugaj-OTA.yaml

Teraz Python bez problemu zweryfikuje certyfikat GitHuba, pobierze brakujący plik cmake-3.30.2-macos-universal.tar.gz i dokończy kompilację Twojego projektu!

Uwaga! Wykonałem dwa pierwsze kroki i to wystarczyło. Pięknie się skompilowało i wysłało do esp32.

Login
Login