OpenMQTTGateway installeer je op een ESP32, ESP8266 of Arduino. Je sluit dan op je microcontrollerbordje transceivers aan voor 433,92MHz-golven, bluetooth low-energy, infrarood, LoRa of gms/gprs. De software ontvangt data van sensoren die deze protocollen gebruiken en stuurt ze in de vorm van MQTT-boodschappen naar je MQTT-broker. Je domoticasysteem zoals Home Assistant kan die boodschappen dan zo ook oppikken en de sensordata visualiseren.

De mogelijkheden zijn vrij divers omdat je zelf je eigen gateway kunt bouwen. In dit artikel zetten we drie gateways op: een voor bluetooth low-energy en twee voor 433,92MHz-golven. We gaan ervan uit dat je al een MQTT-broker hebt draaien, bijvoorbeeld op een Raspberry Pi. Een populaire broker is Mosquitto, die je rechtstreeks op Raspberry Pi OS kunt installeren, in Docker of als add-on in Home Assistant.

PlatformIO

De betrouwbaarste manier om OpenMQTTGateway te configureren en installeren is met PlatformIO. Hiervoor moet je eerst Visual Studio Code installeren. Open daarna links Extensions (de vier blokjes), zoek naar platformio, klik op PlatformIO IDE / Install.

Daarna komt er in de linkerbalk onderaan een icoontje bij, van PlatformIO. Klik erop en dan op PIO Home / Platforms. Zoek naar espressif en installeer Espressif 32. PlatformIO is nu klaar voor ESP32-projecten.

BLE-gateway

Om een gateway voor bluetooth low-energy (BLE) te maken, heb je maar één component nodig: een ESP32-ontwikkelbordje. De ESP32-microcontroller heeft immers BLE ingebouwd. Je kunt het ook doen met een ESP8266 waarop je een HM10-module voor BLE aansluit, maar een ESP32 werkt beter. Wij gebruikten een Olimex ESP32-Gateway met externe antenne, ethernetpoort en bijbehorende behuizing. Een goedkoper bordje werkt ook, maar dat zal sensoren op een grotere afstand dan niet meer zien.

Open via www.bit.ly/omqttrelease de GitHub-pagina met releases voor OpenMQTTGateway en download daar de nieuwste versie van het bestand Source code (zip). Pak het uit en open de uitgepakte map in PlatformIO (File / Open Folder). Het bestand platformio.ino wordt automatisch geopend.

Configuratie

Het belangrijkste stel je in onder ENVIRONMENT CHOICE: het bordje waarvoor je de code wilt compileren. Dat doe je door de puntkomma (;) voor de juiste regel weg te halen. Voor de Olimex ESP32-Gateway waarbij je ethernet gebruikt, is dat:

default_envs = esp32-olimex-gtw-ble-eth

Sla je wijziging op. Verdere configuratie gebeurt in het bestand User_config.h in de map main. Vul zeker de gegevens in voor de regels MQTT_USER, MQTT_PASS en MQTT_SERVER in. Scrol dan naar de sectie met als titel DEFINE THE MODULES YOU WANT BELOW. Wil je dat de MQTT-boodschappen het formaat gebruiken dat Home Assistant automatisch herkent, haal dan de twee commentaartekens (//) weg in het begin van onderstaande regel en sla je wijzigingen op:

//#define ZmqttDiscovery "HADiscovery"

Installatie

Nu je configuratie in orde is, kun je je ESP32-bordje via usb aansluiten. Klik dan onderaan in de blauwe statusbalk van PlatformIO op het witte pijltje naar rechts. Een andere optie is een terminalvenster te openen in het menu Terminal / New Terminal en dan deze opdracht uitvoeren:

pio run --target upload

Als alles goed gaat, krijg je op het einde in het groen de status SUCCESS te zien en staat OpenMQTTGateway op je ESP32. Als je een foutmelding krijgt dat PlatformIO de poort van je apparaat niet vindt, kijk dan na of je de usb-kabel wel correct hebt aangesloten. Indien dat het geval is, zoek dan op welke UART-chip voor seriële communicatie er in je ESP32-bordje zit. Voor de Olimex ESP32-Gateway is dat bijvoorbeeld de CH341. Die wordt normaal gezien standaard al herkend op Windows, macOS en Linux, maar indien nodig moet je nog een driver installeren.

MQTT-boodschappen

Als je nu je bordje via ethernet op je netwerk aansluit en dan stroom geeft, duurt het niet lang voor het de BLE-pakketten uit de lucht haalt en omzet naar MQTT-boodschappen. Die kun je bekijken in een programma zoals MQTT Explorer. Maak daarin een nieuwe verbinding aan met je MQTT-broker. Vul de juiste hostname en het poortnummer in, en indien nodig een gebruikersnaam en wachtwoord.

Kijk nu onder het MQTT-onderwerp home/OpenMQTTGateway_ESP32_OLM_GTWE/BTtoMQTT. Hier vind je per ontdekt BLE-apparaat een bericht waarvan het onderwerp het MAC-adres van het apparaat is en de boodschap een JSON-string met data zoals:

{"id":"E7:2E:00:B1:38:96","name":"LYWSD02","rssi":-74,"distance":5.270232,"model":"LYWSD02","hum":48}

Ons voorbeeld is een bericht van de Xiaomi Mijia LYWSD02-temperatuursensor, met de huidige waarde voor de luchtvochtigheid ("hum": 48).

Home Assistant

Als je in Home Assistant via Instellingen / Integraties je MQTT-broker hebt toegevoegd en in OpenMQTTGateway de Home Assistant MQTT Discovery hebt ingeschakeld, zal Home Assistant de door je ESP32 ontdekte apparaten automatisch herkennen. Je kunt ze aan je Lovelace-dashboard toevoegen door rechtsboven op het menu-pictogram te klikken (pictogram met de drie streepjes), dan Configureer UI, nog eens op het menu-pictogram en dan Ongebruikte entiteiten.

Home Assistant maakt ook enkele sensoren en schakelaars aan voor speciale MQTT-berichten die OpenMQTTGateway heeft gedefinieerd. Zo is er een binaire sensor gedefinieerd die aangeeft of je gateway verbonden is, en met de schakelaar switch.restart_omg herstart je OpenMQTTGateway op afstand. 

Je kunt nog meer opdrachten via MQTT versturen met MQTT Explorer of een andere MQTT-client. In de documentatie van OpenMQTTGateway’s BLE-gateway vind je hoe je MAC-adressen opneemt op een blacklist of whitelist, de tijd tussen BLE-scans instelt en apparaten met een lage signaalsterkte eruit filtert.

Veilige verbinding met MQTT

Sonoff RF Bridge 433 MHz

Als je nog klassieke draadloze temperatuursensoren in huis hebt of producten van KAKU (KlikAanKlikUit), dan kun je die ook met OpenMQTTGateway moderniseren en aan je MQTT-broker en/of Home Assistant koppelen. Een leuk kant-en-klaar apparaatje hiervoor is de Sonoff RF Bridge 433 MHz. Dit is een bordje met ESP8285-microcontroller (een ESP8266 met 1 MB flashgeheugen ingebouwd) en een extra EFM8BB1-controller die RF-signalen decodeert.

Voor de Sonoff RF Bridge dien je weer de configuratiestappen te doorlopen. Haal in het bestand platformio.ini het commentaarteken (;) weg voor deze regel:

;default_envs = rfbridge

Als je eerder onze stappen voor de Olimex ESP32-Gateway hebt gevolgd, zet je het commentaarteken terug bij de regel voor dat apparaat.

De Sonoff RF Bridge heeft geen ethernet, dus daar dien je wifi in te schakelen. Standaard zet OpenMQTTGateway een hotspot op waarmee je verbindt om de wifi-instellingen in te voeren, maar als je de twee commentaartekens (//) aan het begin van onderstaande regel weglaat, kun je in de regels eronder het SSID en wachtwoord van je wifi-accesspoint instellen:

//# define ESPWifiManualSetup true

De instellingen voor MQTT en Home Assistant Discovery blijven hetzelfde als bij de ESP32-Gateway. Sla je wijzigingen op.

Sonoff RF Bridge flashen

De Sonoff RF Bridge flash je niet zomaar via usb. Daarvoor heb je een seriële usb-naar-TTL-adapter nodig. Open de behuizing van de RF Bridge door onderaan de vier rubberen voetjes te verwijderen: eronder zitten schroeven. Heb je die eruit geschroefd, dan gaat de behuizing open. Haal het printplaatje eruit. Aan de componentenkant zijn de centrale chips bedekt met iets wat een glasplaatje lijkt. Dat is een grote groene led die het logo van Sonoff in de behuizing belicht. Trek het voorzichtig naar boven, waarna de lijm loskomt en de componenten eronder toegankelijk worden.

Je ziet nu een schuifschakelaar. Zet die alvast op OFF. Ernaast zie je een rij pin-gaatjes met de aanduiding SDA, GND, TX, RX, 3V3. Het vierkante gat is 3V3 en de SDA heb je niet nodig. Neem nu een seriële usb-naar-TTL-adapter en zorg dat die op 3,3 V staat. Bij ons model kun je daarvoor een jumper over twee pinnetjes zetten. Sluit vier male/female-jumperwires op de pinnen VCC, GND, RX en TX van de adapter aan. Steek de andere, mannelijke kant van de jumperwires in de gaatjes van de RF Bridge, maar wissel RX en TX om: RX van de adapter gaat naar TX van de RF Bridge en andersom.

Houd nu de pinnen in de RF Bridge goed vast, zodat het contact niet verbreekt, en houd de resetknop naast de micro-usb-poort ingedrukt. Sluit de seriële adapter via usb op je computer aan en laat dan de resetknop lost. Druk daarna in Visual Studio Code onderaan op het pijltje om OpenMQTTGateway naar de RF Bridge te flashen. Als het niet onmiddellijk lukt, controleer dan of alle verbindingen correct zijn aangesloten. Nadat het flashen is gebeurd, verwijder je de jumperwires en zet je de schakelaar weer op ON.

Van radiosignaal naar MQTT

Als je nu de RF Bridge met een usb-kabel voedt, verbindt OpenMQTTGateway met je wifi-netwerk en zo met je MQTT-broker. Als je bijvoorbeeld op een ondersteunde RF-knop drukt of een RF-deurcontactsensor opent, krijg je een overeenkomende MQTT-boodschap. In MQTT Explorer zou je die dan moeten zien in het onderwerp home/OpenMQTTGateway_SRFB/SRFBtoMQTT. De MQTT-boodschap is JSON-code en ziet er als volgt uit:

{"raw":"2B660186042E00E7E5","value":"59365","delay":"1111","val_Thigh":"390","val_Tlow":"1070"}

Dat werkt ook in de andere richting: als je in MQTT Explorer rechts onder het kopje Publish bij Topic de regel home/OpenMQTTGateway_SRFB/commands/MQTTtoSRFB invult en in het tekstveld eronder de boodschap {“value”:1315156} (met json als type), en daarna op Publish klikt, zet de RF Bridge dat om in het overeenkomstige radiosignaal en zendt dat uit.

Home Assistant

Als je in Home Assistant MQTT Discovery hebt ingeschakeld, zullen ook de RF-signalen door Home Assistant worden herkend. De sensor sensor.gatewaysrfb bevat dan de code van het laatst ontvangen signaal, het getal in value dus in de JSON-code van hierboven. In je automatiseringen kun je dan reageren op nieuwe waardes van deze sensor.

Ook hier kun je weer speciale opdrachten via MQTT versturen voor extra flexibiliteit. Bekijk de documentatie van OpenMQTTGateway’s RF-gateways.

Zelfbouw voor 433,92 MHz

De Sonoff RF Bridge ondersteunt standaard maar een beperkt aantal apparaten. Wil je meer flexibiliteit, dan kun je een hardwarehack uitvoeren (zie het kader ‘Hack je Sonoff RF Bridge’). Maar een eenvoudiger manier is een zelfbouwoplossing met de SRX882-ontvanger en de STX882-zender. Beide componenten zijn kleine printplaatjes waarop je alleen nog enkele pinnen en een meegeleverde antenne hoeft te solderen. Het zijn goedkope componenten die je voor enkele euro’s vindt.

We tonen hier hoe je met de SRX822, STX822 en een ESP8266-bordje een 433,92MHz-gateway maakt. Prik de drie bordjes op een breadboard en sluit VCC en GND van de 433,92 MHz-bordjes op 3V3 respectievelijk GND van de ESP8266 aan. Sluit dan DATA van de STX822 (het kleinste bordje, de zender) aan op RX van de ESP8266, en DATA van de SRX822 (het grotere bordje, de ontvanger) aan op D3 van de ESP8266.

Hack je Sonoff RF Bridge

Configuratie voor 433,92 MHz

Voor de configuratie heb je nu meerdere mogelijkheden: RF (RCSwitch), RF2 of pilight. De ontwikkelaars zijn ook met een extra mogelijkheid bezig, rtl_433. Bekijk in de documentatie welke configuratie welke apparaten ondersteunt. Zo werkt RF2 voor KAKU (KlikAanKlikUit) en pilight ondersteunt allerlei draadloze temperatuursensoren.

Voor pilight verloopt dit als volgt. Schakel in platformio.ini deze regel in:

default_envs = nodemcuv2-pilight

In User_config.h kun je dezelfde wifi-configuratie als hiervoor voor de Sonoff RF Bridge gebruiken. Het flashen is eenvoudig: sluit het ESP8266-bordje via de micro-usb-kabel aan op je pc en upload dan de code naar het bordje.

Ontvang draadloze sensoren

Als je nu bijvoorbeeld een ondersteunde deurcontactsensor opent, ontvangt de SRX822 dit radiosignaal en stuurt het dat door via MQTT. Het resultaat vind je in een MQTT-boodschap met als onderwerp home/OpenMQTTGateway_ESP8266_Pilight/PilighttoMQTT. De inhoud daarvan is een JSON-tekst zoals het volgende:

{"message":{"id":861780,"unit":9,"state":"opened"},"protocol":"arctech_contact","length":"861780","value":"861780","repeats":2,"status":2}

Aan het id en de unit onderscheid je verschillende deurcontactsensoren van elkaar. Voor andere apparaten ziet de JSON-code er anders uit. Zo zal een temperatuursensor geen onderdeel state hebben, maar temperature en humidity.

Zend radiosignalen

Ook in de andere richting werkt dit: je kunt een MQTT-boodschap uitsturen, waarna OpenMQTTGateway die oppikt en omzet in een radiosignaal. Test dat uit in MQTT Explorer door te publiceren op het onderwerp home/OpenMQTTGateway_ESP8266_Pilight/commands/MQTTtoPilight. De boodschap die je daar invult, is een MQTT-code van de volgende vorm:

{"message":{"systemcode":12,"unitcode":22,"off":1},"protocol":"elro_400_switch"

Als alles goed gaat, kun je zo op afstand draadloze schakelaars controleren. Let op: deze radiosignalen zijn niet versleuteld, dus iedereen in de buurt met een eigen OpenMQTTGateway-gateway of een andere installatie met 433,92MHz-zender kan dezelfde opdrachten geven!

OTA-updates

OpenMQTTGateway heeft standaard al de mogelijkheid voor over-the-air-updates (OTA) ingebouwd. Zodra de firmware op je bordje staat, kun je zo vanuit PlatformIO updates via het netwerk naar je bordje uploaden. Het best kopieer je de sectie met de omgeving van je bordje uit platformio.ini en plaats je deze in een bestand met de naam production_env.ini. Daaraan voeg je dan enkele opties toe voor de OTA-functionaliteit. Voor de Olimex ESP32-Gateway ziet dat er als volgt uit:

[platformio]

default_envs =

esp32-olimex-gtw-ble-eth-ota

[env:esp32-olimex-gtw-ble-eth-ota]

platform = ${com.esp32_platform}

board = esp32-gateway

board_build.partitions = min_spiffs.csv

lib_deps =

${com-esp.lib_deps}

${libraries.ble}

build_flags =

${com-esp.build_flags}

'-DZgatewayBT="BT"'

'-DLED_INFO=33'

'-DLED_INFO_ON=1'

'-DESP32_ETHERNET=true'

'-DGateway_Name="OpenMQTTGateway_ESP32_OLM_GTWE"'

upload_protocol = espota

upload_port = 192.168.0.243

upload_flags =

--auth=OTAPASSWORD

--port=8266

upload_speed = 512000

monitor_speed = 115200

Hierin duid je eerst de standaardomgeving aan. Daarna heb je de omgeving voor je ESP32-Gateway, maar met enkele extra’s: we definiëren als uploadprotocol espota, met als uploadpoort het ip-adres van de ESP32 en dan nog enkele flags, zoals het OTA-wachtwoord dat in User_config.h staat ingesteld, en de poort waarop het uploaden gebeurt. Upload je nu de code opnieuw, dan gebeurt dat niet via de usb-kabel (die hoeft zelfs niet aangesloten te zijn), maar via het netwerk.

Toch maar professioneel laten doen?