Hoe ESPHome te installeren met Home Assistant — Complete gids

ESPHome is een open-source firmwareframework waarmee je gewone microcontrollers — zoals ESP32, ESP8266 en RP2040 boards — kunt omzetten in volledig bestuurbare smart home-apparaten.

Een apparaat “configuratie” in ESPHome bestaat uit een of meer YAML-bestanden. Op basis van deze bestanden compileert ESPHome aangepaste firmware die je direct op je apparaat kunt installeren. Alle hardware die in de configuratie is gedefinieerd — sensoren, schakelaars, lampen, enz. — verschijnt automatisch in de interface van Home Assistant.

ESPHome bestaat uit twee hoofdonderdelen:

1. De firmware die op je microcontroller draait.

2. De beheertool die op je computer of server draait (bijv. een Raspberry Pi, laptop of desktop) — in deze gids gebruiken we de ESPHome Device Builder add-on voor Home Assistant, die een eenvoudige web UI biedt om configuraties te maken, te bewerken en te installeren.

1. De ESPHome Device Builder Add-on installeren

De makkelijkste manier om te beginnen is door ESPHome als een Home Assistant add-on te installeren.

Stappen:

1. Ga in Home Assistant naar Instellingen → Add-on Store.

2. Search for ESPHome and click Install.

3. Wacht tot de installatie is voltooid (dit kan een minuut of twee duren).

4. Klik op Start en vervolgens op Open Web UI om de Device Builder te starten.

Opmerking: Als je Home Assistant-installatie geen add-ons ondersteunt, kun je ESPHome Device Builder apart in Docker draaien.

2. Je eerste configuratie maken

Wanneer je de Web UI voor de eerste keer opent, zal een setupwizard je begeleiden bij het maken van je eerste apparaatconfiguratie.

Je moet:

• Voer een apparaatnaam in (kleine letters met koppeltekens wordt aanbevolen).

• Selecteer je bordtype (bijv. ESP32 DevKit v1).

• Geef je Wi‑Fi SSID en wachtwoord op zodat het apparaat na het flashen verbinding kan maken met je netwerk.

Tip: De allereerste installatie op een nieuw apparaat is vaak de meest ontmoedigende stap. Als je dit nog nooit hebt gedaan, bekijk dan de gids Fysiek verbinden met je apparaat.

3. De firmware voor de eerste keer flashen

Na het maken van je configuratie moet je deze op je apparaat installeren:

1. Verbind je bord via USB met de Home Assistant-host.

2. Klik in ESPHome op Installeren en kies de USB-optie.

3. Eenmaal geflasht, maakt het apparaat verbinding met je Wi‑Fi en communiceert met Home Assistant.

4. Verkennen van de Device Builder-interface

Het startscherm van de ESPHome Device Builder toont al je apparaatconfiguraties ("nodes"). Voor elke configuratie kun je:

• Bijwerken — als de ESPHome-versie van het apparaat ouder is dan de versie van de add-on.

• Bewerken — open de YAML-configuratie-editor.

• Logs — bekijk apparaatslogs via USB/serieel of via Wi‑Fi.

• Overflow-menu — toegang tot extra acties:

  • Valideren — controleer de configuratie op fouten.

  • Installeren — open het installatiedialoog.

  • Schone buildbestanden — verwijder gegenereerde buildbestanden om compileerproblemen op te lossen.

  • Verwijderen — verwijder de configuratie.

Opmerking: Configuratiebestanden worden opgeslagen in <HOME_ASSISTANT_CONFIG>/esphome/. Directe toegang kan de SSH-add-on vereisen en het uitschakelen van de “Beschermingsmodus” — beoordeel de beveiligingsimplicaties voordat je dit doet.

5. Functionaliteit toevoegen aan je apparaat

Voorbeeld: GPIO Schakelaar

Open het YAML-bestand van je apparaat in de editor en voeg toe:

 
schakelaar:
  - platform: gpio
    naam: "Woonkamer Ontvochtiger"
    pin: GPIO5
  

Dit maakt een schakelaar-entiteit aan in Home Assistant die alles bestuurt wat op GPIO5 is aangesloten — het kan een lamp, ventilator of een ander apparaat zijn.

In het bovenstaande voorbeeld voegen we simpelweg een schakelaar toe die "Woonkamer Ontvochtiger" heet en verbonden is met de pin GPIO5. Deze schakelaar kan werkelijk alles bedienen – bijvoorbeeld lampen of een tafelventilator. De naam en functie zijn willekeurig en moeten worden ingesteld zoals passend is voor jouw specifieke toepassing.

Voorbeeld: Binaire Sensor

Om de status van een GPIO-pin te monitoren (bijv. een raamcontactsensor), voeg toe:

  - platform: gpio
    naam: "Woonkamerraam"
    pin:
      nummer: GPIO0
      omgekeerd: true
      modus:
        input: true
        pullup: true
  

Klik na het bewerken op Opslaan om je wijzigingen op te slaan.

6. Je apparaat bijwerken

Het opslaan van het YAML-bestand werkt het apparaat niet automatisch bij. Elke keer dat je wijzigingen aanbrengt:

1. Klik op Installeren om de firmware opnieuw te compileren.

2. Installeer het opnieuw op het apparaat.

Als ESPHome al op het apparaat is geïnstalleerd, kun je het draadloos (OTA) bijwerken zonder USB opnieuw aan te sluiten.

7. Het apparaat verbinden met Home Assistant

 INTEGRATIE TOEVOEGEN AAN MIJN

Zodra het apparaat is geflasht en verbonden met Wi-Fi:

• Home Assistant zou het automatisch moeten ontdekken (als je netwerk mDNS ondersteunt).

• Als dat niet het geval is, ga dan naar Instellingen → Apparaten & Services → Integratie toevoegen, zoek naar ESPHome en voer de hostnaam van het apparaat in (bijv. living-room-lamp.local) of het IP-adres.

Herhaal dit proces voor elk ESPHome-apparaat dat je toevoegt.

8. Waar ga je hierna naartoe

🎉 Gefeliciteerd — je hebt je eerste ESPHome-project opgezet en aangepaste firmware op je apparaat geïnstalleerd! Je hebt ook geleerd hoe je basiscomponenten via YAML toevoegt.

Volgende stappen:

• Blader door de  Componentenindex om alle ondersteunde hardware te vinden.

• Bekijk de FAQ voor veelgestelde vragen.

• Als je problemen ondervindt of functies wilt aanvragen, open dan een ticket op de  GitHub issue tracker.