dahlen.org

ESP8266 via esphomelib mit Home Assistant verbinden

In zwei der vergangenen Posts habe ich beschrieben, wie einfach sich Home Assistant als Steuerzentrale für Heimautomatisierung einrichten lässt und wie man mit einem ESP8266 und der ESPeasy-Firmware ein Relais via WLAN schalten kann. Es liegt nahe einen weiteren Artikel über die Verbindung dieser beiden Elemente zu schreiben, um den ESP direkt aus Home Assistant anzusprechen – und dank esphomelib wird es noch einfacher, als erwartet.

Laut der Projektbeschreibung auf Github handelt es sich bei esphomelib von Otto Winter um „a framework for using your ESP8266/ESP32 devices with Home Assistant“. Und tatsächlich ist esphomelib mehr als eine weitere Firmware für ESP8266/ESP32 MCUs: Neben entsprechenden Bibliotheken werden auch Werkzeuge geliefert, welche das Erstellen und Einspielen angepasster Firmware zum Kinderspiel machen. Vor allem aber ist esphomelib auf die einfache Verbindung mit Home Assistant ausgerichtet und nutzt hierfür das MQTT-Discovery Feature von HA

Home Assistant MQTT Discovery

Bei MQTT-Discovery wird die MQTT-Anbindung von Home Assistant aktiviert und es wird auf eingehende (Konfigurations-) Nachrichten auf vorgegebenen Kanälen (Topics) gelauscht. Die so gewonnenen Informationen werden von HA genutzt um automatisch neue Geräte (Entity) einzurichten. Details finden sich in der Dokumentation von Home Assistant.

Um MQTT-Discovery mithilfe des in HA eingebetteten MQTT Brokers zu aktivieren, ist folgende Ergänzung in der configuration.yaml von Home Assistant vorzunehmen:

mqtt: 
  discovery: true
  username: homeassistant
  password: mypassword

Sollte ein externer Broker eingesetzt oder weitere Einstellungen vorgenommen werden, ist entsprechend der Anleitung zu verfahren. Ein Passwort ist seit Home Assistant 0.76 Pflicht.

Anschließend ist Home Assistant neu zu starten. Wer – wie ich – Home Assistant in einem Docker-Container laufen lässt, muss entweder den Port 1883 durchschleifen (docker -p 1883:1883 …) oder das Host-Network verwenden (docker –net=host …). War die Konfiguration korrekt und der Neustart erfolgreich, taucht ein neues Symbol in den Entwickler-Werkzeugen von HA auf ().

esphomelib / esphomeyaml

Um die Installation und Verwendung von esphomelib erheblich zu vereinfachen, stellt Otto Winter ein Werkzeug namens esphomeyaml zur Verfügung. esphomeyaml unterstützt bei der Erzeugung einer esphomelib-Konfiguration auf YAML-Basis, sowie bei der Erzeugung und Übertragung der der daraus abgeleiteten Firmware. Es wird auch ein Docker-Image angeboten, welches alle Abhängigkeiten für esphomelib enthält.

Anlegen einer Konfiguration mit Docker und esphomeyaml

Der folgende Abschnitt ist im Wesentlichen eine Zusammenfassung der Getting Started with esphomeyaml Anleitung für die Verwendung mit Docker. Zunächst wird der Wizard von esphomeyaml verwendet, um eine Basis-Konfiguration zu erstellen.

docker run --rm -v "$PWD":/config -it ottowinter/esphomeyaml myfile.yaml wizard

Der Befehl startet einen temporären Docker-Container, in welchem der esphomeyaml-Assistent ausgeführt wird und interaktiv bei der Erstellung einer Konfiguration (Dateiname myfile.yaml) unterstützt. Die (aktuell) 5 Bereiche mit teilweise mehreren Fragen sind ausführlich dokumentiert, daher hier in aller Kürze:

Core und Platform

name
Ein symbolischer Name, welcher u.a. in Home Assistant Verwendung findet. Erlaubt sind Buchstaben, Ziffern und der Unterstrich. Empfohlen wird der Raumname, in welchem der MCU zum Einsatz kommt (z.B. wohnzimmer)
ESP32/ESP8266
Plattform, welcher der MCU zugeordnet wird. Neben ESP8266 werden auch die moderneren ESP32-Module unterstützt. Die Frage dient der Vorauswahl für die möglichen Antworten der nächsten Frage. Für den Wemos D1 Mini ist hier ESP8266 zu wählen.
board
Hier ist das verwendete Board genauer zu spezifizieren. Eine Liste der unterstützten Boards (und der jeweiligen Kürzel) findet sich bei platform.io. Für den Wemos D1 Mini ist hier d1_mini anzugeben.

Wifi

Der nächste Satz an Fragen beschäftigt sich mit dem zu nutzenden WLAN Netzwerk. Es werden nacheinander die Netzwerk-Kennung (SSID), sowie das Passwort (PSK) abgefragt.

MQTT

Schließlich werden Details zum zu nutzenden MQTT-Broker abgefragt, im Detail

  • die IP-Adresse des MQTT-Brokers
  • ein eventueller Benutzername für den Zugriff
  • ein Passwort für den Zugriff auf den MQTT-Broker

Wird – wie in diesem Beispiel – der interne MQTT-Broker von Home Assistant verwendet, entspricht die IP-Adresse der des (Docker-) HA-Hosts, Username und Password sind entsprechend der MQTT-Konfiguration in Home Assistant vorzunehmen.

Over-the-Air

Ein weiteres cooles Feature ist die Möglichkeit zum Over-the-Air-Update (OTA), welches genutzt werden kann, sobald die esphomelib-Firmware erstmalig erfolgreich (via USB) auf die MCU überspielt wurde. Aus Sicherheitsgründen kann hierfür ein Kennwort vergeben werden.

Anpassen der Konfiguration

Als Ergebnis des vorherigen Abschnitts findet sich im aktuellen Verzeichnung nun eine Datei namens myfile.yaml, welche die Basics der Firmware definiert. Nun gilt es die mit dem Board verbundenen Geräte einzutragen und somit via MQTT (und damit über Home Assistant) steuerbar zu machen.

Für das auf dem Wemos D1 verbundene Relais aus dem letzten Post ist folgender Abschnitt in myfile.yaml zu ergänzen:

switch:
  - platform: gpio
    name: "steckdose"
    pin: D1

Damit wird esphomelib konfiguriert, gegenüber Home Assistant einen Schalter (switch) auszuweisen und eingehende Schaltbefehle über den GPIO-Pin D1 des Wemos D1 Mini abzubilden. Sind weitere Geräte (z.B. Sensoren) mit dem ESP8266 verbunden, ist die myfile.yaml entsprechend zu erweitern. Eine Liste der unterstützten Komponenten und entsprechende Konfigurationsbeispiele finden sich in der esphomeymal-Dokumentation.

Firmware erstellen und übertragen

Ist die Konfiguration vollständig, kommt wieder Docker zum Einsatz, um die Firmware zu erstellen, zu übertragen und auf dem ESP auszuführen. Vorher ist die MCU natürlich mit dem PC via USB zu verbinden. Unter Linux wird dabei ein serielles Device (z.B. /dev/ttyUSB0) angelegt, welches an den Docker-Container durchgeleitet werden muss. Außerdem muss der Container im „privileged“ Modus laufen, um die Firmware übertragen zu können. Alles nicht weiter schwierig:

 docker run --rm -v "$PWD:/config" -v /dev/ttyUSB0:/dev/ttyUSB0 \
  --privileged -it ottowinter/esphomeyaml myfile.yaml run

Der Prozess läuft weitestgehend automatisch ab. Lediglich der Weg zur Firmware-Übertragung ist zu wählen. Bei erstmaliger Bespielung ist hier der USB-zu-serielle Port zu wählen, sollte esphomelib bereits auf dem MCU sein, kann auch OTA gewählt werden.

Found multiple serial port options, please choose one:
[0] /dev/ttyUSB0 (USB2.0-Serial)
[1] Over The Air (d1mini_1.local)

Nach der Übertragung bleibt die Verbindung zum Wemos D1 Mini offen und das Gerät wird neu gestartet. Boot und andere Meldungen (z.B. die Verbindung zum WLAN und zum MQTT-Broker) werden via Docker-Container ausgegeben, bis dieser beendet wird (mittels Strg-c). Die eigentliche Firmware läuft natürlich auch danach weiter.

Nutzung in Home Assistant

Durch die Verwendung von MQTT-Discovery wird der an den Wemos angeschlossen Switch (das Relais) direkt in Home Assistant angelegt. In der Zustandsansicht () wird es – gemäß meinem Beispiel als switch.steckdose geführt. Dort besteht auch die Möglichkeit über das -Symbol einen Test-Dialog zu öffnen und sich vom (hoffentlich) erfolgreichen Ergebnis der Operation zu überzeugen.

HA „switch“ ausgeschaltet
HA „switch“ angeschaltet

Latenz

Das nachfolgende Video demonstriert die geringe Latenz zwischen der Anforderung in Home Assistant und der Umsetzung durch esphomelib. Home Assistant inkl. des eingebetteten MQTT-Brokers laufen dabei auf einem Raspberry Pi 3B. Das Mobiltelefon und der D1 Mini sind im gleichen WLAN, also per Access Point und Gigabit-LAN mit dem Raspberry verbunden. Das sichtbare Kabel geht zu einer USB Power-Bank. Eine Verzögerung zwischen Antippen des User Interfaces und Schalten des Relais (rote LED) ist faktisch nicht feststellbar.

Fazit

Die Verwendung von esphomelib bzw. esphomeyaml für ESP-Module in Verbindung mit dem MQTT-Discovery-Feature von Home Assistent ist aktuell die einfachste, mir bekannte Möglichkeit diverse Aktoren oder Sensoren zu kontrollieren und zu steuern. Die vom esphomelib-Projekt bereitgestellten Werkzeuge greifen sehr gut ineinander und erlauben die Konfiguration und Übertragung der Firmware auch ohne Programmier-Kenntnisse.

Für Verwender von HASS.io, der „Appliance“-Variante von Home Assistant existiert sogar ein entsprechendes Add-On, um esphomelib/esphomeyaml direkt aus HASS.IO anzusteuern. Sogar eine web-basierte Variante des Wizards wird hier geboten.

Weiterführende Informationen

Software und Dokumentation

Produkte*

Die folgenden Produkte wurden im Artikel besprochen bzw. verwendet:

christoph

,
, , ,