ESP32 en ESP8266 flashen met ESP Web Tools

Communicatie via de seriële interface

ESP Web Tools doet wat het zegt: het is een tooltje waarmee je online, via de webbrowser, ESPHome en andere custom roms kunt installeren op ESP-microcontrollers. In dit artikel leren we je hoe dat werkt, hoe je de tool configureert en hoe je de beveiliging ervan regelt.

Wie al eens aangepaste firmware op een microcontrollerbordje heeft geflasht, mag niet bang zijn voor de opdrachtregel. Doorgaans moet je lokaal ontwikkeltools installeren, waarmee je je firmware bouwt en via een USB-kabel naar het flashgeheugen van het bordje uploadt. Voor minder ervaren gebruikers is dat vaak een drempel om aangepaste firmware te installeren. Het project ESP Web Tools biedt aanbieders van firmware voor de ESP8266 en ESP32 een oplossing, zodat gebruikers de installatie eenvoudigweg vanuit hun webbrowser kunnen doen.

Laten we beginnen bij het begin. De populaire ESP8266- en ESP32-microcontrollerbordjes zijn voorzien van een USB-poort, die zich bij het aansluiten op je pc als seriële interface aanbiedt. In Windows is dat een com-poort, in Linux een apparaatbestand zoals /dev/ttyUSB0 of /dev/ttyACM0 en in macOS een apparaatbestand waarvan de naam begint met /dev/tty.usbserial-.

De firmware in je microcontrollerbordje kan via die seriële interface in twee richtingen communiceren met je pc, bijvoorbeeld om logs door te sturen of om opdrachten aan te nemen. Dat doe je met een terminalemulatorprogramma zoals PuTTY, GNU Screen, minicom en nog vele andere.

Traditioneel gebeurt communicatie met een microcontroller via een terminalemulatorprogramma zoals GNU Screen op de opdrachtregel.

Web Serial

Er zijn heel wat omstandigheden waarin je van de gebruiker niet kunt verwachten dat hij op de opdrachtregel commando’s intypt of thirdpartysoftware moet installeren om met je apparaatje te communiceren. Je verspreidt bijvoorbeeld een apparaat onder gebruikers die niet gewend zijn om met de opdrachtregel of software zoals PuTTY te werken. Of je wilt op een Chromebook of een Android-telefoon verbinden met je apparaat.

Voor die situaties is de Web Serial API ontwikkeld, die je toelaat om in je webbrowser te lezen van en te schrijven naar seriële apparaten. Die apparaten kunnen verbonden zijn via een klassieke seriële poort of via USB of bluetooth die een seriële poort emuleren. Web Serial API is geen W3C-standaard, maar een specificatie gepubliceerd door de Web Platform Incubator Community Group van het W3C.

Voorlopig is Web Serial alleen ondersteund in Chrome 78 en hoger, Edge 79 en hoger en Opera 65 en hoger. In het begin moest je daarvoor nog experimentele functionaliteit in je webbrowser inschakelen, maar sinds Chrome/Edge 89 en Opera 76 is Web Serial standaard ingeschakeld. Op webbrowsers zonder Web Serial die wel WebUSB ondersteunen, zoals Chrome voor Android, kun je de API gebruiken via de Web Serial-polyfill. Op CodeSandbox vind je enkele voorbeelden van het gebruik van de polyfill.

Veiligheid en mogelijkheden

Websites die toegang hebben tot apparaten die aan je pc hangen; het klinkt een beetje eng. Hoe zit het dan met de beveiliging? Mozilla is duidelijk in zijn officiële verklaring over Web Serial: “Devices that offer serial interfaces often expose powerful, low-level functions over the interface with little or no authentication. Exposing that sort of capability to the web without adequate safeguards presents a significant threat to those devices.” Dat is dan ook de reden waarom Firefox geen ondersteuning biedt voor de Web Serial API.

Toch zijn er wel degelijk 'safeguards' ingebouwd in de implementatie van Web Serial, en de specificatie gaat uitgebreid in op de beveiligingsoverwegingen. Een webpagina die JavaScript-code bevat die de Web Serial API gebruikt, toont een melding aan de gebruiker, die moet klikken op het apparaat waarmee hij wil verbinden. Het vereist dus een expliciete actie van de gebruiker. De webpagina krijgt ook alleen maar toegang tot het apparaat dat de gebruiker heeft aangeklikt en kan dus niet opvragen welke apparaten er allemaal aangesloten zijn.

De verbinding blijft ook maar open zolang je de webpagina open hebt. Ververs of sluit je een webpagina die een seriële verbinding heeft geopend, dan wordt de verbinding gesloten. Er wordt ook altijd een icoontje getoond op het tabblad van de pagina zolang de verbinding open is.

Web Serial werkt ook alleen over Https, tenzij je de webpagina op je pc host en via localhost benadert. Je hoeft dus niet bang te zijn dat er gevoelige gegevens van je apparaten onversleuteld over internet worden verspreid. En een man-in-the-middleaanval waarbij er bytes in de communicatie tussen de webpagina en je apparaat worden geïnjecteerd, is zo ook niet mogelijk. Het belangrijkste risico is een phishingaanval, waarbij een website zich voordoet voor een andere. Daardoor zou je mogelijk aan de verkeerde website seriële toegang tot je apparaat geven.

Bij gebruik van Web Serial moet je de website altijd eerst toestemming geven voor toegang tot een specifiek apparaat. — Bij het gebruik van Web Serial moet je de website altijd eerst toestemming geven voor toegang tot een specifiek apparaat.

Mogelijkheden van Web Serial

Wat is er dan zoal mogelijk met Web Serial? Alles wat lokale software met seriële communicatie kan doen. Zo biedt de website serialterminal.com een seriële terminalemulator op het web aan. Wil je logs bekijken die een apparaatje op zijn seriële interface aanbiedt, dan hoef je de USB-kabel maar aan te sluiten, de website serialterminal.com te openen, de baudrate in te stellen, op 'Connect' te klikken en je apparaat te kiezen. Daarna zie je de boodschappen voorbij scrollen. De broncode van de website is open. Het Google Chrome-team heeft als demoapplicatie voor de Web Serial API ook een serialterminal ontwikkeld, waarvan de broncode beschikbaar is. Dit project ondersteunt de Web Serial-polyfill en werkt zo bijvoorbeeld ook op Chrome voor Android.

De Adafruit WebSerial Plotter, waarvan de broncode ook vrijgegeven is, komt dan weer van pas voor projectjes waarbij een microcontrollerbordje sensordata naar de seriële interface stuurt in csv-formaat. De plotter toont de waardes dan in verschillende kleuren op een grafiekje, net zoals de Serial Plotter in de Arduino IDE dat doet. Meer interessante projecten vind je op het Reddit-forum r/WebSerialAPI. Wil je zelf met de Web Serial API aan het ontwikkelen gaan, lees dan zeker Getting started with the Web Serial API op Codelabs of Read from and write to a serial port op web.dev, allebei websites van Google.

Met de seriële terminal van Google bekijk je in je webbrowser logs van aangesloten apparaten.

Esptool in de webbrowser

Seriële communicatie wordt niet alleen gebruikt voor logs, maar ook om firmware naar het flashgeheugen van een microcontroller te uploaden. Voor de ESP8266 en ESP32 gebeurt dat met Espressifs programma esptool, dat via de seriële interface met de rombootloader van deze chips communiceert.

Esptool is eenvoudig te installeren als Python-pakket met pip install esptool, maar zoals we zagen, is de lokale installatie van ontwikkeltools niet altijd aangewezen of mogelijk. Adafruit ontwikkelde daarom twee jaar geleden Web Serial ESPTool, waarmee je in een Web Serial-compatibele webbrowser firmware naar Espressifs microcontrollers kunt uploaden. De broncode is beschikbaar onder de MIT-licentie.

Ondertussen ontwikkelde Espressif zijn JavaScript-implementatie van esptool met Web Serial, esptool-js. Naast de versie op GitHub Pages kun je ook de broncode downloaden, de afhankelijkheden installeren met npm install en daarna met python3 -m http.server 8080 een lokale webserver opzetten. De webinterface is dan beschikbaar op http://localhost:8080/.

ESP Web Tools

Adafruits Web Serial ESPTool en Espressifs esptool-js zijn in feite slechts webgebaseerde versies van esptool. Ze vereisen dan ook nog altijd wat voorkennis van de gebruiker. Zo moet de gebruiker een baudrate kiezen, een flashadres instellen en het juiste firmwarebestand selecteren.

Nabu Casa, het bedrijf achter Home Assistant en ESPHome, ontwikkelde daarom ESP Web Tools als gebruiksvriendelijke wrapper. Initieel baseerde Nabu Casa zich daarvoor op Adafruits Web Serial ESPTool, en even nam het bedrijf dit project zelfs over als officiële beheerder, maar in juli schakelde Nabu Casa voor ESP Web Tools over naar esptool-js.

ESPHome-mediaspelers

Een voorbeeld van de gebruiksvriendelijkheid is te zien op de webpagina ESPHome Media Players. Deze installeert een ESPHome-configuratie op je apparaatje waarmee je er een mediaspeler van maakt die je rechtstreeks vanuit Home Assistant aanstuurt. Je sluit gewoon je apparaat (Raspiaudio ESP Muse Luxe, Raspiaudio ESP Muse Proto, M5Stack Atom Speaker Kit of M5Stack Atom Echo Development Kit zijn ondersteund) via USB aan, selecteert het in de lijst en klikt op 'Connect', waarna de melding van Web Serial komt om een seriële interface te kiezen. Als je geen apparaat vindt en annuleert, geeft de webpagina een handige checklist van wat je kunt proberen om het probleem op te lossen, zoals een andere kabel of de installatie van de juiste drivers.

Nadat de verbinding met je apparaat is opgezet, krijg je de vraag om of de firmware te installeren, of een console te openen om de logs te bekijken. Kies je voor de installatie en bevestig je, dan wordt de firmware op het bordje geïnstalleerd. Bij sommige apparaten moet je de bootknop ingedrukt houden terwijl je de installatie start. Bij onze M5Stack Atom Echo moesten we de resetknop aan de zijkant indrukken vlak voordat we op het installatieknopje van de webpagina drukten.

Met ESP Web Tools installeer je firmware op een ESP32 of ESP8266 vanuit je webbrowser.

Wifi configureren via de seriële interface

Daarna komt nog iets extra’s wat ESP Web Tools zo gebruiksvriendelijk maakt: de configuratie van het wifinetwerk. Traditioneel maakt een wifiapparaat waarop je nieuwe firmware installeert een eigen accesspoint aan, waarop je dan aanmeldt en het eigenlijke wifinetwerk kiest waarop je het wilt laten verbinden. ESPHome biedt dat nog altijd aan, en ook bij de mediaplayerfirmware die we op onze M5Stack Atom Echo installeerden, was dat nog mogelijk. Maar deze aanpak verloopt niet altijd even vlot.

ESP Web Tools maakt daarom optioneel gebruik van Improv Wi-Fi, een door ESPHome en Home Assistant ontwikkelde standaard om apparaten met wifi te verbinden door de ssid en het wachtwoord via Bluetooth Low Energy of een seriële verbinding door te geven. Beide manieren zijn ook in de webbrowser ondersteund, namelijk via Web Bluetooth respectievelijk Web Serial. Improv Wi-Fi laat je dus toe om vanuit je webbrowser een aangesloten apparaat eenvoudig met je wifinetwerk te verbinden, zonder dat je eerst met een tijdelijk accesspoint op het apparaat moet verbinden.

In de praktijk kan er met Improv Wi-Fi nog altijd iets mislopen waardoor de gebruiker afhaakt. Toen we de mediaspelerfirmware van ESPHome op onze M5Stack Atom Echo geïnstalleerd hadden met ESP Web Tools, moesten we eerst het bordje resetten voordat we op de webpagina de mogelijkheid 'Connect to Wi-Fi' te zien kregen. Dat kan door op 'Logs & Console' te klikken en dan 'Reset device'.

Na de klik op 'Connect to Wi-Fi' kies je de ssid uit de lijst van gevonden wifinetwerken, vul je het wachtwoord in en klik je dan op 'Connect'. De webpagina stuurt die credentials dan via de seriële verbinding die openstaat dankzij Web Serial naar het apparaatje. Daarna klik je gewoon op 'Add to Home Assistant' om het apparaat in Home Assistant te importeren. Je kunt ook in het dashboard van ESPHome klikken op 'Adopt' om het ontdekte apparaat toe te voegen. Dat werkt via de functie dashboard_import van ESPHome.

Overigens biedt ESPHome met ESPHome Web een vereenvoudigde variant van ESPHome in je webbrowser aan. Ze laat je toe om met behulp van ESP Web Tools van een aangesloten ESP-bordje de logs te bekijken, wifi te configureren als de firmware al Improv Wi-Fi aanbiedt, of er een firmwarebestand op te installeren of er een basisversie van ESPHome op te installeren die je in je ESPHome-dashboard kunt integreren.

Met Improv Wi-Fi configureer je het Wi-Fi-netwerk van je microcontroller via de seriële interface. — Met Improv Wi-Fi configureer je het wifinetwerk van je microcontroller via de seriële interface.

ESPHome-firmware met ESP Web Tools verspreiden

Voor gebruikers is ESP Web Tools dus een handige manier om firmware te installeren, maar wat moet de ontwikkelaar ervoor doen die zijn firmware op deze manier wil aanbieden? Ontwikkel je je firmware met ESPHome, dan is de gemakkelijkste manier om een nieuwe GitHub-repository te genereren op basis van het ESPHome Project Template. Dit bevat een voorbeeldconfiguratie en GitHub-workflow die automatisch je firmware bouwt en via GitHub Pages op een webpagina met ESP Web Tools plaatst zodat gebruikers je firmware zo kunnen installeren.

Om dit te testen, heb ik mijn bestaande ESPHome-project omgezet naar dit sjabloon: M5Stack-Air-Quality-ESPHome. Het resultaat is te zien op de bijbehorende GitHub Pages-url van het project. In het YAML-bestand is het belangrijk dat je improv_serial: of esp32_improv: zet voor gebruik van Improv Wi-Fi via Web Serial of Web Bluetooth. Dit laatste werkte bij mijn ESPHome-configuratie niet omdat de BLE-component zoveel geheugen gebruikte dat de wificomponent niet correct geïnitialiseerd raakte.

Met GitHub Actions publiceert het project een bin-bestand met de firmware en een bestand manifest.json in de branch gh-pages van de repository. Genereer je firmware voor meerdere chipfamilies (ESP8266, ESP32, ESP32-C3, ESP32-S2 of ESP32-S3), dan wordt er voor elke familie een map aangemaakt met het firmwarebestand en manifest. Er wordt ook een globaal manifest aangemaakt met informatie over alle firmwarebestanden. Dat ziet er bijvoorbeeld als volgt uit:

{
  "name": "M5Stack Air Quality ESPHome",
  "version": "",
  "home_assistant_domain": "esphome",
  "new_install_skip_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32",
      "parts": [
        {
          "path": "m5stack-air-quality-kit-esp32/m5stack-air-quality-kit-esp32.bin",
          "offset": 0
        }
      ]
    }
  ]
}

Dit ESPHome-project is specifiek ontworpen voor één bordje van M5Stack met een ESP32. Als je firmware voor meerdere chipfamilies aanbiedt, komt er voor elke chipfamilie in dit globale manifest een extra build. ESP Web Tools zal automatisch op basis van de chipfamilie in het microcontrollerbordje dat je aansluit de juiste firmware uploaden.

Uiteindelijk moet je dan alleen nog maar in je html-bestand, of je Markdown-bestand voor GitHub Pages, de volgende html-elementen opnemen:

<esp-web-install-button manifest="./manifest.json"></esp-web-install-button>
<script type="module" src="https://unpkg.com/esp-web-tools@8.0.3/dist/web/install-button.js?module"></script>

Het element esp-web-install-button toont de knop 'Connect' waarmee alle functionaliteit van ESP Web Tools wordt gestart. Het attribuut 'manifest' laat je verwijzen naar de locatie van het bestand manifest.json.

Andere projecten en conclusie

Als je verschillende firmware voor verschillende ontwikkelbordjes wilt publiceren, ook al behoren ze tot dezelfde chipfamilie, dan kan ESP Web Tools niet automatisch de juiste firmware bepalen. Je kunt dan in JavaScript een uitklapmenu programmeren dat de gebruiker de juiste firmware laat kiezen, of je plaatst op je webpagina gewoon een webinstallatieknop voor elk apparaat. Van die laatste aanpak vind je een voorbeeld in het project ESPHome-Air-Quality-Monitor, dat één ESP8266- en twee ESP32-configuraties ondersteunt. Het belangrijkste verschil is dat je met GitHub Actions nu voor elke configuratie een firmwarebestand en bijbehorend manifest publiceert, en dat je in elke knop op je webpagina naar een ander manifest verwijst.

Als je niet van GitHub Pages gebruik wilt maken, moet je wel zorgen dat je webserver een geldig https-certificaat heeft, bijvoorbeeld met gebruik van Let’s Encrypt. Als het manifest of de firmwarebestanden op een andere server staan dan het html-bestand, dan moet de webserver met een CORS-header (Cross-Origin Resource Sharing), zoals Access-Control-Allow-Origin: https://domain-of-firmware-website.com, aanduiden dat je webbrowser die bestanden daar mag downloaden.

Geef de keuze uit meerdere firmwarebestanden om met ESP Web Tools te flashen.

Andere projecten

Hoewel ESP Web Tools in de schoot van ESPHome is ontwikkeld, was het vanaf het begin de bedoeling om het ook voor andere projecten open te stellen. Ondertussen gebruiken diverse ‘concurrerende’ projecten van ESPHome de oplossing dan ook om hun firmware via het web op apparaten van gebruikers te installeren. Onder andere WLED, Tasmota, ESPEasy, CanAirIO en OpenMQTTGateway zetten ESP Web Tools in.

Ook voor je eigen niet op ESPHome gebaseerde firmware voor Espressifs chipfamilies, bijvoorbeeld met gebruik van ESP IDF of Arduino, kun je zo’n installatiepagina opstellen. De website van ESP Web Tools legt je stap voor stap uit hoe je het aan je website toevoegt. Vooral voor het manifest kun je nog allerlei opties instellen. Je zult dan je CI-builds moeten uitbreiden, zodat ze naast de firmwarebestanden ook een manifest voor ESP Web Tools creëren. Al met al is ESP Web Tools een open en flexibele technologie waarmee ontwikkelaars een groter publiek voor hun firmware voor Espressifs microcontrollers kunnen aantrekken.