Maak je eigen domotica-apparaten met esphomeyaml

Home Assistant maakt het heel eenvoudig om van je Raspberry Pi een domoticacontroller te maken. Zou het niet handig zijn als je even eenvoudig sensoren en andere apparaten voor je domoticasysteem kunt maken? Met esphomeyaml is dat mogelijk.

In het vorige nummer van Linux Magazine toonden we je hoe je Home Assistant (https://www.home-assistant.io/) op een Raspberry Pi installeert en zo een domoticacontroller maakt waarover je volledige controle hebt, met eindeloze mogelijkheden en dat voor een fractie van de prijs van commerciële domoticacontrollers.

We toonden ook hoe je apparaten aan je domoticasysteem toevoegt, bijvoorbeeld Z-Wave-apparaten. We gingen daar minder diep op in, omdat iedereen andere vereisten heeft en andere domotica-apparaten in huis haalt. Maar net zoals je met Home Assistant je eigen domoticacontroller maakt, bestaan er ook projecten om je eigen domotica-apparaten te maken. Een ervan is speciaal ontwikkeld om naadloos met Home Assistant samen te werken: esphomeyaml (https://esphomelib.com/esphomeyaml/). In dit artikel duiken we in esphomeyaml, zodat je over enkele pagina’s je eigen domotica-apparaten kunt maken die automatisch in je Home Assistant verschijnen zonder dat je ze telkens in Home Assistant dient te configureren.

Esphomeyaml en esphomelib

Je ziet vaak verwijzingen naar de naam esphomelib en vaak worden esphomeyaml en esphomelib ook door elkaar gebruikt, wat verwarrend is. Esphomelib is een C++-framework om aangepaste Arduino-firmware voor de esp8266 en esp32 te maken. Gebruik je esphomelib rechtstreeks, dan dien je dus C++-code te schrijven. Esphomeyaml is een Python-programma dat op basis van een yaml-bestand C++-broncode creëert die van esphomelib gebruikmaakt, die code compileert en naar je apparaat uploadt. Werk je met esphomeyaml, dan definieer je de werking van je apparaat dus in een yaml-bestand. Maar wil je bijvoorbeeld componenten aan je apparaat toevoegen die esphomeyaml niet ondersteunt, dan kun je perfect de door esphomeyaml gegenereerde C++-code uitbreiden met je aangepaste code voor de ondersteuning.

Wat heb je nodig?

Uiteraard heb je eerst een Home Assistant-installatie nodig, daarvoor verwijzen we naar het artikel in het vorige nummer van Linux Magazine. We gaan hier ervan uit dat je de installatie via Hass.io (https://www.home-assistant.io/hassio/) hebt gedaan, waardoor we de esphomeyaml-ondersteuning eenvoudig kunnen installeren via een add-on.

Je hebt ook een microcontrollerbordje met een esp8266 of esp32 van Espressif nodig. Beide worden ook wel eens NodeMCU genoemd. Ook de Sonoff-apparaten van iTead (https://sonoff.itead.cc/en/) zijn ondersteund, zoals de draadloze schakelaars Sonoff Basic (met één relais), Sonoff 4CH (met vier relais) en Sonoff S20 (een slimme stekker). Deze bevatten allemaal een esp8266.

Daarnaast dien je elektronische componenten op je microcontrollerbordje aan te sluiten om er een sensor of actuator van te maken. Dat kan in een voorlopige opstelling met een breadboard en jumperdraden en daarna op een stripboard of printplaatje gesoldeerd.

 

Wifi en mqtt

De communicatie met de esp8266 of esp32 verloopt via wifi. Je Home Assistant-installatie en je esphomeyaml-apparaten dienen dus met hetzelfde wifi-netwerk te verbinden. Bovendien heb je ook een mqtt-broker nodig om de boodschappen tussen esphomeyaml-apparaten en Home Assistant uit te wisselen. Mqtt (Message Queuing Telemetry Transport) is een protocol voor data-uitwisseling dat veel wordt gebruikt in IoT-toepassingen.

Als je nog geen mqtt gebruikt, is de eenvoudigste manier om de ingebouwde mqtt-broker van Home Assistant te activeren. Dat doe je met de regel mqtt: in het configuratiebestand configuration.yaml van Home Assistant. Merk op: dit stelt geen wachtwoord in. Lees op https://www.home-assistant.io/docs/mqtt/broker hoe je een wachtwoord instelt en hoe je een externe mqtt-broker gebruikt. Overigens kun je ook eenvoudig de mqtt-broker Mosquitto installeren als add-on voor Home Assistant (https://www.home-assistant.io/addons/mosquitto/).

Daarna moet je ook MQTT Discovery (https://www.home-assistant.io/docs/mqtt/discovery/) inschakelen. Dat gaat met de volgende code in je configuration.yaml:

mqtt:
  discovery: true
  discovery_prefix: homeassistant

Herstart Home Assistant na deze wijzigingen.

 

Andere projecten

Esphomelib is niet de enige manier om zelf domotica-apparaten te maken van een esp8266 of esp32. Je kunt perfect een eigen Arduino-sketch schrijven, omdat Arduino veel extra bibliotheken heeft met ondersteuning voor allerlei componenten. Maar dan moet je de integratie met Home Assistant en zaken zoals ota-updates wel zelf regelen. Voor de esp8266 heb je ESPEasy (https://www.letscontrolit.com/wiki/index.php/ESPEasy), en er is ook experimentele ondersteuning voor de esp32. Voor de iTead Sonoff-apparaten (waarin een esp8266 zit) heb je de firmware Sonoff-Tasmota (https://github.com/arendst/Sonoff-Tasmota). Dit zijn beide goede platforms om snel aan de slag te gaan, maar voor integratie met Home Assistant zijn nog wat manuele stappen nodig en zodra je iets wilt aanpassen, heb je ook extra werk.

Installatie

Klik links in de webinterface van Home Assistant op het paneel van Hass.io en dan op het tabblad Add-on Store. Voeg dan een nieuwe repository toe met als url https://github.com/OttoWinter/esphomeyaml en klik op Add. Daarna krijg je onderaan je pagina met add-ons een nieuw onderdeel esphomeyaml HassIO Add-On Repository waar je de keuze krijgt uit drie add-ons: esphomeyaml, esphomeyaml-beta en esphomeyaml-edge. Kies de eerste voor een stabiele versie, de tweede voor een bètaversie en de derde voor de nieuwste experimentele toevoegingen.

Klik op een van de add-ons (we raden de eerste aan zolang je geen specifieke functies van de nieuwere versies nodig hebt) en dan op Install. De installatie duurt een tijdje, dus je dient wat geduld te hebben. Stel na de installatie het wachtwoord in en klik op Save. Klik daarna op Start om de add-on op te starten.

Klik op Open web UI om het dashboard van esphomeyaml te openen. Dat dashboard werkte op onze Ubuntu 18.04-machine overigens niet helemaal correct in Firefox 61; Chromium 68 kon er wel mee overweg.

Je kunt net zoals we dat in het vorige artikel deden dit dashboard aan het zijpaneel van Home Assistant toevoegen door een panel_iframe in het bestand configuration.yaml te definiëren. Als je dat handiger vindt, zoek dan in Linux Magazine 5 nog eens op hoe dat verloopt.

Je eerste node configureren

Omdat je nog geen domotica-apparaat hebt gedefinieerd (esphomeyaml noemt het een ‘node’), is het dashboard nog leeg. Klik op de pulserende plusknop bovenaan rechts om een nieuwe node toe te voegen. Geef je node een naam met alleen kleine letters, cijfers en een underscore en klik op Continue.

In de volgende stap vul je het type microcontroller in (ESP8266 of ESP32), evenals het type van je controllerbordje. Voor dat laatste word je doorverwezen naar de documentatie van het ontwikkelplatform PlatformIO. Zoek je bordje op die documentatiepagina, klik op de pagina specifiek voor je bordje en zoek daar het ID op. Voor een NodeMCU is dat bijvoorbeeld nodemcuv2, voor Sonoff-apparaten esp01_1m. Klik daarna op Continue. Wij kiezen voor onze test een NodeMCU-bordje met een esp8266.

In de volgende stap voer je het ssid en wachtwoord voor je wifi in, zodat de node met je draadloos netwerk kan verbinden. En als je de node ook via wifi wilt updaten zodat je alleen de eerste keer de firmware via usb dient te uploaden, stel je het best een ota-wachtwoord in zodat niet ieder apparaat op je wifi-netwerk zomaar je node kan updaten met willekeurige firmware. Klik op Continue.

In de laatste stap dien je de mqtt-instellingen in te voeren. Esphomeyaml gebruikt mqtt immers om met Home Assistant te communiceren. Vul hier het ip-adres van je mqtt-broker in en indien nodig de gebruikersnaam en het wachtwoord. Klik op Continue en daarna op Submit.

 

Firmware uploaden

Je krijgt nu in je dashboard de configuratie van je node te zien. Als je op Validate klikt, krijg je het volledige configuratiebestand te zien in yaml-formaat. Met een klik op Compile compileer je de firmware voor je node. Het compileren duurt de eerste keer heel lang, omdat esphomeyaml ook alle benodigde bibliotheken dient te compileren. De volgende keren gaat het veel sneller.

Nadat dit is voltooid, download je met een klik op Download binary de firmware. Die kun je dan zelf naar je node uploaden, bijvoorbeeld via een seriële verbinding of via een webformulier in bestaande firmware op je node, zoals Sonoff-Tasmota of ESPEasy.

Maar esphomeyaml kan ook rechtstreeks de firmware compileren en daarna naar je node uploaden. De eerste keer dient dat via usb te verlopen, daarna kan het via wifi. Gebruik je de Hass.io add-on zoals we in dit artikel doen, dan kan esphomeyaml wel geen apparaten herkennen die je na de start van de add-on aansluit. Sluit daarom je node via usb aan op je Raspberry Pi en herstart dan in het paneel van Hass.io de add-on.

Kies in het dashboard van esphomeyaml bovenaan rechts de usb-poort waarop je je node hebt aangesloten en klik dan bij je node op Upload. Als het is voltooid, kun je de usb-kabel verwijderen. Klik dan in het dashboard bij je node op Show Logs. Plaats je node nu elders en sluit die op stroom aan met een voedingsadapter of batterij. In de logs zou je nu moeten zien dat je node met mqtt verbindt.

Leds

Voorlopig doet onze node nog niets nuttigs. Daarom gaan we de twee on-board leds van onze NodeMCU activeren (één op het NodeMCU-bordje en één op de ESP-12-module daarop). Open het configuratiebestand van je node, bijvoorbeeld met de add-on Configurator (zie Linux Magazine 5). De bestandsnaam vind je in het dashboard van esphomeyaml bij je node. Je ziet dat het een eenvoudig yaml-bestand is met de basisconfiguratie van je node.

Onderaan voeg je nu de volgende yaml-code toe:

switch:
  – platform: gpio
    name: “ESP-12 LED”
    pin:
      number: GPIO2
      inverted: True
  – platform: gpio
    name: “NodeMCU LED”
    pin:
      number: GPIO16
      inverted: True

Als je wat vertrouwd bent met de configuratie van Home Assistant, is deze code zeker geen Chinees voor je. Esphomeyaml maakt immers van een gelijkaardige syntax gebruik. We definiëren twee pinnen en configureren ze als inverted omdat de leds aan gaan als je 0 naar de pin schrijft en uit gaan als je 1 naar de pin schrijft.

 

Over-the-air update

Sla het bestand op en klik dan in het dashboard van esphomeyaml weer op Upload. De aangepaste code wordt nu opnieuw gecompileerd en via wifi naar je node geüpload. Als je geen mDNS gebruikt, lukt dat mogelijk niet. Dan moet je aan het wifi-gedeelte van de yaml-code de volgende code toevoegen om een statisch ip-adres in te stellen en deze firmware nog één keer via usb uploaden.

wifi:
  ssid: MIJNSSID
  password: MIJNWACHTWOORD
  manual_ip:
    static_ip: 10.0.0.42
    gateway: 10.0.0.1
    subnet: 255.255.255.0

 

Esphomeyaml gebruikt daarna ook dit ip-adres om de code via wifi te uploaden.

 

Automatisch ontdekt

Door de MQTT Discovery ontdekt Home Assistant nu automatisch je esphomeyaml-node zodra die online komt. En als je de standaard view gebruikt, verschijnt je node daar ook automatisch in. Dat is vooral handig als je meerdere esphomeyaml-nodes gaat aanmaken of ze regelmatig aanpast. Je hoeft je configuratie dan alleen maar in esphomeyaml te doen en niet meer in Home Assistant zelf.

In ons voorbeeld betekent dit dat je twee schakelaars te zien krijgt in Home Assistant: ESP-12 LED en NodeMCU LED. Deze kun je in- en uitschakelen, en dan zie je de desbetreffende leds op je NodeMCU-bordje aan en uit gaan.

 

Sensor aansluiten

Uiteraard begint het werk nu pas. Nu kun je allerlei sensoren of andere elektronische componenten op je esp-module aansluiten en die in esphomeyaml configureren. Op https://esphomelib.com/esphomeyaml/ vind je een lijst van de ondersteunde componenten en op elke componentpagina vind je de yaml-code die je nodig hebt om je component te integrreren. We tonen hier als voorbeeld hoe je de -sensor MH-Z19 aansluit en dit in esphomeyaml configureert.

We gebruiken vier pinnen van de MH-Z19: VIN, GND, RX en TX. VIN sluiten we op VIN van de esp-module aan, GND op GND van de esp-module, RX op D5 en TX op D4. Eventueel plaats je nog een condensator tussen GND en 3V3 van de esp-module voor meer stabiliteit; zonder herstart de module regelmatig door spanningspieken.

Maak nu via het dashboard van esphomeyaml een nieuwe node aan of kopieer het yaml-bestand van je node naar een tweede yaml-bestand in de directory /config/esphomeyaml voor je nieuwe node. Verander de naam en het ip-adres en verwijder de configuratie van de on-board leds. Voeg dan de volgende code toe:

uart:
  rx_pin: D4
  tx_pin: D5
  baud_rate: 9600

sensor:
  – platform: mhz19
    co2:
      name: “CO2”
    temperature:
      name: “Temperatuur”
    update_interval: 15s

Als je deze code nu compileert en naar je node uploadt, krijg je het -gehalte (in ppm) en de temperatuur (maar deze sensor is niet zo accuraat) in Home Assistant te zien.

 

En verder

Esphomeyaml heeft nog heel wat meer mogelijkheden. Bekijk zeker de uitstekende documentatie op de website eens. Elk van de daar besproken componenten is op een afzonderlijke pagina nog eens goed gedocumenteerd. Helaas draait de ESP32-toolchain nog niet op de Raspberry Pi. Als je met de ESP32 wilt werken, zul je voorlopig dus esphomeyaml op je pc moeten installeren in plaats van de add-on op Home Assistant te gebruiken.

Tot slot ondersteunt esphomeyaml ook automatisaties op de node zelf (https://esphomelib.com/esphomeyaml/guides/automations.html), zodat je bijvoorbeeld een led op je node kunt laten aangaan als het -gehalte in je huis hoger dan 1000 is. Dat werkt lokaal op je node en functioneert dus ook als je wifi, Home Assistant of je mqtt-broker niet bereikbaar zijn.