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.

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

• esphomelib-Homepage
• esphomelib-Projekt auf Github
• Getting Started with esphomeyaml
• durch esphomelib/platform.io unterstützte Komponenten
• Home-Assistant MQTT Auto-Discovery
• HASS.IO

Produkte*

Die folgenden Produkte wurden im Artikel besprochen bzw. verwendet:

• Wemos D1 Mini bei Ali Express
• Wemos D1 Mini bei Amazon
• Wemos Relay Shield (und Nachbauten) bei Ali Express
• Wemos Relay Shield bei Amazon

Der Beitrag ESP8266 via esphomelib mit Home Assistant verbinden erschien zuerst auf dahlen.org.

Eine lösbare Herausforderung …

Den Zero W gibt es für unter 15 EUR (ohne Zubehör) bzw. für unter 30 Euro als Essential Paket (z.B. bei Amazon). Für die Installation wird eine geeignete Micro-SD-Karte mit mindestens 8GB Kapazität benötigt. Außerdem ein Kartenleser (z.B. von Lexar, bei Amazon), welcher an einen weiteren Rechner angeschlossen wird.

Vorbereitung

Das Bespielen der SD-Karte mit Raspbian lt. Install Guide ist schnell erledigt und mündet folgender Partitionierung:

1. die boot-Partition, welche das DOS-Dateisystem nutzt und
2. die root-Partition, welche das Linux Ext-Dateisystem nutzt.

Wir werden ausschließlich den Inhalt der boot-Partition erweitern, dank DOS-Dateisystem sind die folgenden Änderungen unter allen populären Betriebssystemen möglich.

OpenSSH-Service aktivieren

Gemäß offizieller Anleitung (Abs. 3) ist im Stammverzeichnis der boot-Partition eine Datei namens ssh zu erstellen. Die reine Existenz dieser Datei führt im Raspian-Boot-Prozess dazu, dass der OpenSSH Server automatisch aktiviert wird und eingehende Verbindungen auf Port 22 annimmt.

WLAN-Konfiguration vorbereiten

Der zweite Schritt ist etwas umfangreicher. Ebenfalls im Stammverzeichnis der boot-Partition wird die Datei wpa_supplicant.conf erstellt. Lt. ungeprüfter Aussagen muss sie Linux-Zeilenenden aufweisen. Wie in den Hintergrundinformationen angekündigt, wird diese Datei beim Start automatisch an die richtige Stelle /etc/wpa_supplicant/ verschoben.

Die Datei hat folgenden Inhalt:

country=DE 
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev 
update_config=1 
network={
     ssid="WLAN SSID"
     scan_ssid=1
     psk="WLAN PASSWORT"
     key_mgmt=WPA-PSK
}

Die Werte WLAN SSID und WLAN PASSWORT sind natürlich durch die tatsächlichen Angaben zu ersetzen. Befindet man sich nicht in Deutschland, ist DE durch den ISO-Code des aktuellen Landes zu ersetzen.

Start

Damit sind die Vorbereitungen für den ersten Start abgeschlossen. Die SD-Karte wird nun in den Raspberry Pi gesteckt und dieser mit Energie versorgt. Nach einigen Sekunden sollte der Raspberry Pi im WLAN auftauchen, als Standard-Hostname wird dabei raspberrypi verwendet. Im WLAN-Access Point sollte sich auch die vergebene IP-Adresse ermitteln lassen.

Mittels eines geeigneten SSH-Clients kann nun die Anmeldung erfolgen. Das Passwort zum Standard-Benutzer pi ist in der offiziellen Dokumentation zu finden und sollte nach der 1. Anmeldung unbedingt geändert werden.

Das Verfahren zur WLAN-Client-Definition kann übrigens wiederholt werden und eignet sich somit auch, um eine nachträgliche Änderung headless durchzuführen.

Der Beitrag Raspberry Pi Zero W „headless“ Setup – so geht’s erschien zuerst auf dahlen.org.

Oftmals kommen dabei schwergewichtige Javascript-Lösungen und aberwitzige Berechnungen zum Einsatz, doch ist eine Umsetzung ausschließlich mit HTML und CSS ebenfalls möglich.

Das Ziel

Ich bin mir nicht sicher, ob fly-out die korrekte Bezeichnung ist (und nehme entsprechende Hinweise aus Kommentaren gerne zur Kenntnis), aber den Effekt dürften viele schon gesehen haben:

• ein Bild wird im unteren Bereich von einem (einzeiligen) Text nebst Hintergrund überlagert. Die Bildunterschrift liegt also auf dem Bild.
• wird der Mauszeiger über das Bild bewegt, so rollt der überlagernde Text-Bereich nach oben und gibt weitere Text-Passagen frei.
• wird der Mauszeiger aus dem Bild bewegt, fällt der Text wieder auf seine ursprüngliche Höhe zusammen.

Ein Bild sagt mehr als tausend Worte, daher hier ein Beispiel für das zu erreichende Ziel (bitte Mauszeiger über das Bild bewegen).

Der Weg

Die Lösung basiert – wie bereits angekündigt – auf reinem HTML-Markup und Styling über CSS-Regeln. Zur semantischen Abbildung des Konstrukts bietet sich das mit HTML 5 neu eingeführte figure-Element nebst seines Kind-Elements figcaption an. Notwendig ist dies allerdings nicht, auch andere Lösungen mit <div> oder <dl>, <dt> und <dd> sind möglich.

HTML Mark-Up


<figure>
<img src="https://placehold.it/600x300" alt="placeholder">
<figcaption>
<h1>Bildunterschrift</h1>
<p>Weiterführender Text zum Bild
(kann auch mehrere Paragraphen enthalten)</p>
</figcaption>
</figure>


Das reine HTML führt zu dem unten abgebildeten Ergebnis. Da noch spezifisches Styling fehlt, kommen die Standardwerte des jweiligen Browsers zum Einsatz.

Cascading Stylesheets

Um unserem Ziel näher zu kommen, wird mit dem grund­sätz­lichen Styling begonnen:


figure {
position: relative;
width: 600px;
overflow: hidden;
line-height: 0;
}
figure img {
max-width: 100%;
}
figure figcaption {
position: absolute;
bottom: 0;
width: 90%;
padding: 0 5%;
background-color: rgba(0,0,0,0.8);
color: white;
}


• das figure-Element bekommt eine definierte Breite, an der sich die Inhalte (also Bild und Text) orientieren. Außerdem wird die Zeilenhöhe (line-height) auf 0 gesetzt, um unerwünschten Abständen durch Umbrüche im HTML entgegenzuwirken.
• das figcaption-Element bekommt 5% Innenabstand (padding) zu beiden Seiten, damit der enthaltene Text nicht an die Ränder stösst. Es wird außerdem am unteren Rand ausgerichtet (bottom).
• Vorder- und Hintergrund-Farbe des Overlays werden definiert.

Optisch ist das erreichte Zwischenergebnis schon recht nahe am geplanten Ziel, aber noch bewegt sich nichts. Ändern soll dies Verwendung der transition-Vorschrift auf dem max-height-Attribut des figcaption-Elements. Ziel ist es, daß im Ursprungszustand max-height für die Darstellung der Überschrift (<h1>) ausreicht und diese Beschränkung im hover-Zustand aufgehoben wird.

Es gilt nun also die notwendige (Achtung: Kein Widerspruch) minimale Maximal-Höhe zu finden, welche sich aus der Höhe (height) des h1-Elementes zzgl. seiner Abstände und Rahmen ermitteln lässt. Damit das Ganze nicht in einer Pixel-Orgie ausartet und auch im Rahmen eines Responsive Design funktioniert, empfehle ich die Verwendung von em, also der relativen Zeichengröße:


figure figcaption h1 {
font-size: 2em;
line-height: 1em;
padding: 0.25em 0;
margin: 0;
}


Zur Erklärung:

• zunächst wird die Schriftgröße auf 2em gesetzt, was einer Verdoppelung zur umgebenden Schriftgröße entspricht
• desweiteren wird die Zeilenhöhe auf die aktuelle Schriftgröße gesetzt. Der Wert 1em bezieht sich auf die aktuell gültige Schriftgröße, welche durch die vorherige Zeile auf das Doppelte der normalen Schriftgröße gesetzt wurde.
• außerdem bekommt die Überschrift oberhalb und unterhalb etwas Innenabstand, um atmen zu können. Auch für padding gilt, daß em in Relation zur aktuellen Schriftgröße gesehen werden muß.
• das explizite Setzen des Außenabstands (margin) auf 0 soll die Anwendung von Browers-Vorgaben unterdrücken. Andernfalls würde z.B. Mozilla Firefox hier einen Standardwert von 0,67em anwenden.

Damit hat das h1-Element jetzt – von außen betrachtet – eine Höhe von 3em (2em + 2 × 0,25 × 2em). Dies ist der initiale Wert für das max-height-Attribut des figcaption-Elements. Er wird dafür sorgen, daß im Ursprungszustand nur die einzeilige Überschrift sichtbar sein wird. Gleichzeitig wird diese Beschränkung aufgehoben, sobald der Mauszeiger das figure-Element betritt.

Damit das Ganze nicht schlagartig, sondern schön smooth ’n easy passiert, wenden wir die CSS-Eigenschaft transition auf das max-height-Attribut an. Es ergibt sich folgende CSS-Ergänzung:


figure figcaption {
max-height: 3em;
transition: max-height 1s ease-in-out;
}
figure:hover figcaption {
max-height: 100%;
}


Erläuterung:

• max-height: 3em ist wie oben erläutert der initiale Wert für die maximale Höhe des Text-Overlays.
• transition: max-height sorgt dafür, daß bei Veränderung des max-height-Wertes zwischen Soll- und Ist-Wert interpoliert wird. Die Dauer bis zum Erreichen des Soll-Wertes wird auf 1 Sekunde (1s) gesetzt. Die Veränderung soll dabei nicht linear, sondern mit Beschleunigung und Verzögerung erfolgen (ease-in-out)
• figure:hover figcaption definiert das Verhalten des figcaption-Elementes, sobald der Mauszeiger sich über dem umgebenden figure-Element befindet. Abgebildet wird dies durch die CSS-Pseudoklasse :hover am entsprechenden Element.

Damit haben wir unser Ziel erreicht: Animierte Bildbeschriftungen nur mit HTML und CSS.

Das Fazit

Die hier vorgestellte Lösung stellt eine Alternative zu Ansätzen mit Javascript dar und erlaubt ein Auskommen ohne zusätzliche Bibliotheken wie jQuery. Durch den Fokus auf Standards wie HTML(5) und CSS(3) werden Inkompatibilitäten vermieden und gleichzeitig das Potential moderner Browser ausgenutzt.

Gleichwohl ist sie nicht frei von Nachteilen, die hier kurz aufgeführt sind:

• Geräte ohne Mauszeiger, wie Mobiltelefone und Tablet-PCs, werden den ergänzenden Text nicht zu sehen bekommen. Bei der Formulierung ist also darauf zu achten, daß bereits die Überschrift ausreichend Informationen bereitstellt und sich die weiterführenden Angaben auf anderem Wege ermitteln lassen.
  Dies gilt allerdings auch für Javascript-Lösungen gleichermaßen.
• Versionen des Internet Explorers bis einschließlich Version 9 unterstützen die CSS-Eigenschaft transition nicht. Bei diesen Versionen wird das fly-out also schlagartig erscheinen (s.a. http://caniuse.com).
• das Einfahren des Overlays beim Verlassen des figure-Elementes geschieht mit einer gewissen Verzögerung. Grund hierfür ist, daß die Transition für max-height bei 100% startet, das Overlay aber i.d.R. nicht die volle Höhe des figure-Elementes einnimmt. Die ersten Momente der Höhenreduktion sind daher nicht sichtbar.

Bzgl. des letzten Punktes haben Experimente mit height statt max-height nicht zum Erfolg geführt. Ein Wechsel von einer definierten Höhe (z.B. height: 3em) auf den automatisch ermittelten Wert (height: auto) wurde nicht via transition interpoliert und erfolgte sprunghaft.

Abschließend noch ein Hinweis zur Hintergrund-Farbe des Overlays: CSS3-Farben mit rgba (also Farbe + Transparenz) werden noch nicht von allen Browsern unterstützt. Alternativ kann figcaption darum ein transparentes Bild (PNG) als Hintergrund (background-image) zugewiesen werden. Vermeiden sollte man allerdings opacity, da dies sich auch auf die Schrift auswirkt.

Der Beitrag image caption fly-out: Animierte Bildbeschriftungen nur mit HTML & CSS erschien zuerst auf dahlen.org.