ESP Web Tools: ESP32 im Browser flashen

ESP32 im Browser flashen mit ESP Web Tools oder esptool-js: So funktionieren Web Serial, Manifest und Flash-Offsets, mit einem echten OpenGizmo-Manifest.

Veroffentlicht
Lesezeit
10 Min.
Kategorie
Anleitungen
Ein Mann mit Bart und blauem Hoodie sitzt an einem Laptop, dessen Browser einen orangen Install-Button und einen Fortschritt von 68 % zeigt, ein USB-Kabel führt zum ESP32-Board.

Kurz gesagt

ESP Web Tools flasht einen ESP32 über Web Serial, in Chrome oder Edge auf einer HTTPS-Seite, mit einer manifest.json, die jeden Firmware-Teil und seinen Flash-Offset auflistet. OpenGizmo macht es mit esptool-js genauso.

Ja, du kannst einen ESP32 im Webbrowser flashen. ESP Web Tools, oder jede Seite auf Basis von Espressifs esptool-js, spricht das Board über die Web Serial API an: Du öffnest eine HTTPS-Seite in Chrome oder Edge auf einem Desktop-Rechner, steckst ein USB-Datenkabel an, wählst den seriellen Port und drückst einen Button.

In dieser Anleitung erkläre ich, wie ESP Web Tools funktioniert (Web Serial, die manifest.json, die Offsets) und zeige dann, wie die drei OpenGizmo-Geräte dieselbe Idee nutzen, mit einem echten Manifest auf einem CDN. Vorab ein Detail: Die OpenGizmo-Website bindet den ESP-Web-Tools-Button nicht ein. Sie nutzt esptool-js direkt, und ich zeige dir, warum.

Die vier Schritte beim Flashen im Browser: USB-Port per Web Serial wählen, Chip erkennen, im Manifest den passenden Build wählen, die Teile an ihren Offsets schreiben

Wie funktioniert ESP Web Tools?

ESP Web Tools ist eine Open-Source-Webkomponente des ESPHome-Projekts (Open Home Foundation), die jeder Webseite einen Install-Button für ESP8266- und ESP32-Firmware hinzufügt. Laut der eigenen Website kombiniert es Web Serial, Improv Wi-Fi (optional) und ein Manifest, das die Firmware beschreibt.

Moment, was ist Web Serial? Das ist eine Browser-API, mit der eine Seite serielle Geräte lesen und beschreiben kann, auch USB-Geräte, die einen virtuellen seriellen Port bereitstellen, so wie ein ESP32-Entwicklungsboard. Der Browser zeigt eine Port-Auswahl, und du wählst den Port selbst, eine Seite kann also kein Gerät hinter deinem Rücken öffnen.

Das passiert, wenn jemand den Button drückt:

  1. Der Browser bittet den Nutzer, einen seriellen Port zu wählen.
  2. Das Tool verbindet sich mit dem ROM-Bootloader des Chips und erkennt ihn. Laut Dokumentation wählt es danach automatisch die passende Firmware-Variante aus dem Manifest.
  3. Es lädt die Teile dieses Builds herunter und schreibt jeden an seinen Offset.
  4. Optional wartet es auf Improv Serial, um den Gerätezustand zu erfahren und die WLAN-Einrichtung anzubieten.

Das Flashen selbst wurde nicht neu erfunden. Stand November 2026 hängt das ESP-Web-Tools-Paket (Version 10.5.x) von esptool-js ab, Espressifs JavaScript-Port des esptool-Flashers, sowie vom Improv-Serial-SDK. Deshalb verhalten sich die beiden Tools ähnlich.

Den Button in deine Seite einzubauen braucht zwei Snippets, beide aus der offiziellen Anleitung: Du lädst das Skript, setzt dann das Element ein und zeigst damit auf dein Manifest.

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

<esp-web-install-button manifest="https://example.com/firmware/manifest.json"></esp-web-install-button>
Zeile 3, Spalte 1UTF-8HTML

Welche Browser unterstützen es, und warum HTTPS?

Web Serial gibt es nur in sicheren Kontexten, die Seite mit dem Button muss also über HTTPS ausgeliefert werden. ESP Web Tools nennt das als Web-Serial-Voraussetzung. Außerdem muss der Browser die API implementieren, und das ist die eigentliche Grenze.

BrowserWeb SerialHinweis
Chrome (Desktop)Ja, ab Version 89esptool-js nennt Chrome und Edge ab 89
Edge (Desktop)Ja, ab Version 89In den MDN-Kompatibilitätsdaten identisch mit Chrome
Chrome auf AndroidJa, ab Version 148Die Versionen 138 bis 147 sahen nur Bluetooth-Ports
Firefox (Desktop)Ja, ab Version 151MDN-Daten. Nicht von mir getestet
Firefox auf AndroidNeinMDN-Daten
Safari, jeder Browser auf iOSNeinMDN-Daten. ESP Web Tools sagt ebenfalls: kein iOS

Die Versionen stammen aus den Browser-Kompatibilitätsdaten von MDN, Stand November 2026, und MDN selbst markiert die Funktion als nicht Baseline. Das Verhalten des OpenGizmo-Flashers habe ich nur im Code geprüft, nicht in jedem Browser. Seine Karte zeigt "Flashen in diesem Browser nicht möglich", wenn navigator.serial fehlt oder die Seite kein sicherer Kontext ist.

Wenn du Safari oder ein Smartphone nutzt, flashe einmal mit einem Tool, das auf einem Computer installiert ist: Siehe Arduino IDE vs. PlatformIO für ESP32 oder, für die ESP32-CAM, die Anleitung zum ESP32-CAM-MB-Programmer.

Wie schreibst du das Manifest und wählst die Offsets?

Ein Manifest ist eine kleine JSON-Datei, die dem Flasher sagt, welche Firmware auf welchen Chip kommt. Jeder Build listet die zu schreibenden Dateien (Teile) und den Flash-Offset jeder Datei auf. Das hier ist das kleinste brauchbare Manifest, im Format der ESP-Web-Tools-Dokumentation:

manifest.json
manifest.json
{
  "name": "My Firmware",
  "version": "1.0.0",
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "merged-firmware.bin",
          "offset": 0
        }
      ]
    }
  ]
}
Zeile 15, Spalte 1UTF-8JSON

Pfade der Teile werden relativ zum Manifest aufgelöst und können auch vollständige URLs auf anderen Hosts sein. Die Felder, denen du am ehesten begegnest:

SchlüsselWoWas er bewirkt
name, versionoberste EbeneWerden in der Oberfläche angezeigt. Der Name wird mit der Firmware verglichen, die das Gerät über Improv meldet
builds[].chipFamilyBuildESP8266, ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-P4, ESP32-S2 oder ESP32-S3
builds[].parts[]BuildEin Dateipfad und der ganzzahlige Flash-Offset, an den die Datei geschrieben wird
builds[].serialTypeBuildcdc oder uart: ein eigener Build für natives USB oder für eine USB-UART-Bridge
new_install_prompt_eraseoberste Ebenetrue lässt den Nutzer bei einer Neuinstallation wählen, ob alles gelöscht wird
new_install_improv_wait_timeoberste EbeneSekunden, die nach der Installation auf eine Improv-Antwort gewartet wird (standardmäßig 10, 0 schaltet Improv ab)
home_assistant_domain, funding_urloberste EbeneOptionale Links, die nach der Installation angezeigt werden

Die Offsets hängen vom Chip ab und davon, wie du die Firmware gebaut hast. Für eine Firmware aus vier Dateien legt die ESP-IDF-Dokumentation den Second-Stage-Bootloader auf 0x1000 beim ESP32 und auf 0x0 beim ESP32-S3. Die S3-Seite legt außerdem die Partitionstabelle standardmäßig auf 0x8000. In den PlatformIO-Builds, die ich ausliefere, liegt das boot_app0-Image bei 0xE000 und die App bei 0x10000. Rate nie: Lies sie aus deinem Build, wie es der nächste Abschnitt tut.

Brauchst du eine zusammengeführte Firmware-Datei?

Für einen ESP32, der mit ESP-IDF 4 oder neuer gebaut wurde, sagt die ESP-Web-Tools-Dokumentation: ja. Ihre Begründung: Werden die vier Dateien mit dem esptool-Befehl installiert, passt esptool Flash-Frequenz, -Größe und -Modus an das Zielgerät an, und ESP Web Tools kann das nicht im laufenden Betrieb. Also baust du mit merge_bin ein einziges Image und trägst es bei Offset 0 ein.

Die vier Teile zusammenführen (Befehl aus der ESP-Web-Tools-Dokumentation)
esptool --chip esp32 merge_bin -o merged-firmware.bin --flash_mode dio --flash_freq 40m --flash_size 4MB 0x1000 bootloader.bin 0x8000 partitions.bin 0xe000 boot.bin 0x10000 your_app.bin

Getrennte Teile können ebenfalls funktionieren: Das Beispielmanifest in der README von ESP Web Tools listet vier Dateien, mit einem Bootloader namens bootloader_dout_40m.bin, dessen Flash-Einstellungen schon beim Build festgelegt wurden. Das Zusammenführen ist der dokumentierte Weg, wenn du von einem normalen Build ausgehst. Die Dokumentation nennt zwei Einschränkungen: Nimm dout, wenn dein Speichertyp opi_opi oder opi_qspi ist, und ersetze qio oder qout durch dio. Die zusammengeführte Datei hat einen Preis, den du kennen solltest. Die esptool-Dokumentation sagt, dass im Raw-Format die Lücken zwischen den Dateien mit 0xFF-Bytes aufgefüllt werden, dem Wert von gelöschtem Flash. Ein zusammengeführtes Image deckt also den gesamten Bereich vom Bootloader bis zur App ab, einschließlich des Einstellungsbereichs zwischen Partitionstabelle und boot_app0. Merke dir das für den Abschnitt über Updates.

Wie flasht OpenGizmo im Browser ohne die Webkomponente?

Jede OpenGizmo-Projektseite hat eine Firmware-Karte, die nicht das ESP-Web-Tools-Element ist. Sie ist die Komponente app/components/projects/FlashFirmware.vue im Quellcode der Website, die ESPLoader und Transport aus esptool-js importiert (Version 0.7.1 in der package.json der Website) und ein Manifest im ESP-Web-Tools-Format liest. Das Format ist also gemeinsam, nur das Frontend unterscheidet sich.

Open-Source-Projekt mit ESP32 + MAX7219
Gizmo Ticker

Ein Krypto-Display mit WLAN, gebaut aus einem ESP32, einer MAX7219-LED-Matrix und einer Nuxt-4-Web-App für die Einrichtung und Konfiguration im Browser.

  • Krypto-Ticker in Echtzeit
  • MAX7219-LED-Matrix
  • Einrichtung im Browser
Ansehen

Hier ist das echte Manifest, das die Karte des Gizmo Ticker liest, unter https://cdn.opengizmo.dev/gizmo-ticker/manifest.json (abgerufen am 14. November 2026):

manifest.json
manifest.json
{
  "name": "Gizmo Ticker",
  "version": "v1.2.0",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "parts": [
        {
          "path": "v1.2.0/release-bootloader.bin",
          "offset": 0
        },
        {
          "path": "v1.2.0/release-partitions.bin",
          "offset": 32768
        },
        {
          "path": "v1.2.0/release-boot_app0.bin",
          "offset": 57344
        },
        {
          "path": "v1.2.0/release-firmware.bin",
          "offset": 65536
        }
      ]
    }
  ]
}
Zeile 28, Spalte 1UTF-8JSON

Die Offsets sind dezimal, wie JSON es verlangt: 32768 ist 0x8000, 57344 ist 0xE000, 65536 ist 0x10000. Das Manifest des Gizmo Reolink Switch hat dieselben vier Teile auf demselben Chip. Das Manifest der Gizmo Camera hat "chipFamily": "ESP32" und seinen Bootloader bei 4096 (0x1000), passend zur ESP-IDF-Seite von oben. Die anderen Offsets sind gleich.

Ein Schlüssel in diesen Manifesten ist nur für die offizielle Komponente: new_install_prompt_erase: false. Die OpenGizmo-Karte liest ihn nie. ESP Web Tools würde false wie seinen Standard behandeln, nämlich bei einer Neuinstallation alle Daten zu löschen.

Wenn du auf Firmware flashen drückst, macht die Karte Folgendes, in dieser Reihenfolge:

  1. Ruft navigator.serial.requestPort() auf und verbindet sich mit esptool-js bei 115200 Baud, wodurch der Chip erkannt wird.
  2. Lädt das Manifest mit cache: 'no-store' herunter, damit ein neues Release sofort erscheint.
  3. Sucht den Build, dessen chipFamily dem erkannten Chip-Namen entspricht. Gibt es keinen, bricht sie mit "Diese Firmware ist nicht für den angeschlossenen Chip gebaut" ab, so landet nie ein ESP32-Image auf einem ESP32-S3.
  4. Lädt die vier Teile nacheinander herunter und löst jeden Pfad relativ zur Manifest-URL auf.
  5. Ruft writeFlash auf, mit flashMode, flashFreq und flashSize auf 'keep', eraseAll: false und compress: true.
  6. Setzt das Board zurück.

Warum nicht die Webkomponente nutzen? Ich kann auf drei Dinge im Code verweisen, und ich habe den offiziellen Button nicht mit diesen Manifesten ausprobiert, kann also nicht sagen, wie er sich verhalten würde:

  • Die vier Teile bleiben getrennt. Mit 'keep' lässt esptool-js den Header des Bootloaders so, wie der Build ihn erzeugt hat, es ist also kein Merge-Schritt nötig. Und die Teile überspringen den Einstellungsbereich, den eine zusammengeführte Datei überschreiben würde.
  • Ein Reset-Fix. Ein Kommentar in app/utils/hardReset.js der Website sagt, dass esptool-js nur RTS freigibt, was nichts bewirkt, wenn die Leitung schon freigegeben ist, wie es über das chipeigene USB beim ESP32-S3 der Fall ist. Das Board blieb dann im Bootloader, bis man es abzog. Die Website übergibt einen eigenen Reset: DTR freigegeben, RTS 100 ms gehalten, dann freigegeben.
  • Eine maßgeschneiderte Karte. Sie zeigt die Version vor dem Flashen, vier Phasen (Verbinden, Herunterladen, Flashen, Neustart), ein Log, die Release Notes der Version, die sie installiert, und übersetzte Meldungen.

Die Firmware hat keine Improv-Unterstützung: In den drei Repositories habe ich keinen Improv-Code gefunden. Die erste WLAN-Einrichtung läuft stattdessen über ein Captive Portal. Der Vergleich der WLAN-Provisioning-Methoden behandelt Improv im Vergleich zu den Alternativen, und die Anleitung zur Behebung von Captive-Portal-Problemen behandelt das Portal.

Die vier Flash-Teile des Gizmo Ticker und ihre Offsets, mit dem Einstellungsbereich bei 0x9000 unangetastet

Was ist der kürzeste Weg zu deiner eigenen Installationsseite?

Hier ist die ganze Arbeit der Reihe nach, für deine eigene Firmware:

  1. Baue die Firmware und sammle ihre Teile mit den Offsets (oder eine zusammengeführte Datei bei Offset 0 für ESP Web Tools).
  2. Lade die Teile und eine manifest.json, die sie auflistet, auf einen HTTPS-Host hoch, mit CORS-Headern, falls der Host nicht zur Domain der Installationsseite gehört.
  3. Füge das <script>- und <esp-web-install-button>-Snippet von oben mit der Manifest-URL in eine HTTPS-Seite ein.
  4. Öffne die Seite in Chrome oder Edge auf einem Desktop-Rechner, schließe das Board mit einem Datenkabel an, drücke den Button und wähle den Port.
  5. Prüfe, ob das Board deine Firmware startet und ob die Seite für jeden aufgelisteten Chip den richtigen Build anbietet.

Wo hostest du die Firmware, und was ist mit CORS?

Du kannst Manifest und Teile auf derselben Website wie die Installationsseite hosten, dann ist keine CORS-Einrichtung nötig. OpenGizmo hält sie auf einem CDN (cdn.opengizmo.dev, im Release-Workflow von einem Cloudflare-R2-Bucket gestützt), der Browser stellt also Cross-Origin-Anfragen. ESP Web Tools sagt dir für diesen Fall, dass du Access-Control-Allow-Origin: https://domain-of-your-website.com senden sollst.

Ich habe das am 14. November 2026 geprüft, indem ich das Ticker-Manifest mit Origin: https://opengizmo.dev angefragt habe: Die Antwort enthielt access-control-allow-origin: https://opengizmo.dev und vary: Origin, und eine Preflight-Anfrage lieferte 204 mit access-control-allow-methods: GET. Das CDN erlaubt nur den Origin der Website, nicht *. Teste deins mit curl -I -H "Origin: https://your.site" <manifest-url>.

Wie veröffentlichst du eine neue Version, ohne WLAN-Einstellungen zu verlieren?

Lege die Dateien jeder Version in einen eigenen Ordner, ändere sie nie und verschiebe das Manifest zuletzt. Der Release-Workflow von OpenGizmo macht das bei einem manuellen Lauf von main:

Ein Browser zeigt den Flash-Speicher, der in vier orangen Teilen beschrieben wird, während ein grauer Teil gesperrt und unberührt bleibt, mit einem XIAO an USB-C

  1. Liest VERSION und bricht ab, wenn der Tag existiert oder die Version der Web-App abweicht.
  2. Führt die Web-App-Tests und die nativen Firmware-Tests aus und baut dann die Firmware.
  3. Führt package_firmware.py aus, das PlatformIO nach den Flash-Images und ihren Offsets fragt (pio project metadata) und manifest.json schreibt.
  4. Erstellt ein GitHub-Release mit den Teilen, dessen Notes einen esptool-Befehl zum Flashen über USB enthalten.
  5. Lädt die Teile mit Cache-Control: public, max-age=31536000, immutable hoch, danach das Manifest mit max-age=60.

Das Manifest zuletzt hochzuladen bedeutet, dass die Website nur eine vollständig hochgeladene Version anbietet, und ein Cache von einer Minute lässt ein Release innerhalb einer Minute erscheinen. Die Header, die ich am 14. November 2026 gesehen habe, passen dazu.

Die Einstellungen überleben wegen dessen, was nicht geschrieben wird. Die Projekte nutzen die Partitionstabelle huge_app.csv, in der der Arduino-Core nvs bei 0x9000 (0x5000 Bytes) und otadata bei 0xE000 definiert. Die vier Teile decken die nvs-Region (0x9000 bis 0xDFFF) nicht ab, und eraseAll ist false, also bleiben die Preferences-Daten erhalten. Das folgt aus den Offsets und dem Code. Einen Flash vorher und nachher habe ich nicht gemessen. Die Anleitung zur Partitionstabelle erklärt das Layout, und der OTA-Vergleich erklärt, warum diese Geräte per USB aktualisiert werden, da sie keinen zweiten App-Slot haben.

Lies bei der offiziellen Komponente die Löschregel genau: ESP Web Tools löscht bei einer Neuinstallation alle Daten, außer new_install_prompt_erase ist true und der Nutzer lehnt ab. Es bietet eine Neuinstallation an, wenn es die aktuelle Firmware des Geräts nicht erkennen kann oder wenn die erkannte Firmware nicht zum name im Manifest passt.

Was geht am häufigsten schief?

Die meisten Fehler liegen an Kabel, Port oder Browser, nicht an der Firmware. Arbeite diese Tabelle von oben nach unten ab und ändere immer nur eine Sache.

Was du siehstWahrscheinliche UrsacheWas du versuchen kannst
Button deaktiviert, oder 'Flashen in diesem Browser nicht möglich'Browser ohne Web Serial, oder die Seite nutzt kein HTTPSNimm Chrome oder Edge auf dem Desktop, über HTTPS oder localhost
Die Port-Auswahl zeigt kein GerätUSB-Kabel nur zum Laden, oder das Board wird nicht erkanntNimm ein Datenkabel und einen anderen USB-Port, dann lade die Seite neu
Verbindung schlägt fehl, keine seriellen Daten empfangenDer Chip ist nicht im Download-Modus, oder die USB-Verbindung ist wackeligSiehe die Anleitung zu 'Failed to connect'
'Diese Firmware ist nicht für den angeschlossenen Chip gebaut'Das Manifest hat keinen Build für diese Chip-FamilieFüge einen Build dafür hinzu, oder nimm das richtige Board
'Der Firmware-Download ist mit Status 404 fehlgeschlagen'Der Pfad eines Teils im Manifest ist falschÖffne die URL jedes Teils in einem Tab
Manifest nicht lesbar, mit CORS-Fehler in der KonsoleDas CDN erlaubt den Origin deiner Seite nichtSende Access-Control-Allow-Origin für deine Domain
Das Flashen endet, aber das Board bleibt im BootloaderKein echter Reset-Impuls nach dem FlashenAbziehen und wieder einstecken; ein eigener Hard-Reset wie der oben behebt es

Zur dritten Zeile: Failed to Connect to ESP32: No Serial Data Received geht Boot-Modus, Kabel und Treiber durch. Die Fehlertexte in der Tabelle stammen aus der Übersetzungsdatei der OpenGizmo-Karte, und deine eigene Seite wird etwas anderes anzeigen.

Wo endet das Flashen im Browser?

Flashen im Browser gibt dir eine Seite, auf der jeder mit Chrome oder Edge, einem Kabel und einem Board deine Firmware in einer Minute installieren kann, mit erhaltenen Einstellungen und einer Versionsnummer auf dem Bildschirm. Wir haben die Bausteine durchgesprochen: Web Serial über HTTPS, ein Manifest aus Teilen und Offsets (zusammengeführt für ESP Web Tools, oder vier Teile mit esptool-js), CORS, falls die Dateien woanders liegen, und ein Release, das das Manifest zuletzt hochlädt.

Drei Grenzen bleiben. Es deckt nur das Flashen per Kabel ab; für Updates über WLAN siehe den Vergleich der OTA-Methoden. Die Browser-Unterstützung außerhalb von Chrome und Edge ist Stand November 2026 dünn, und ich habe nichts davon getestet. Und die offizielle Komponente habe ich nur anhand von Dokumentation und Quellcode beschrieben, nicht aus eigener Nutzung. Wenn du das Ganze in Aktion sehen willst, flasht die Bauanleitung für den Gizmo Ticker ein Board von Anfang bis Ende, und jede der drei Projektseiten hat die Karte.

Haufig gestellte Fragen

Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.

Ja. Eine Seite mit ESP Web Tools oder esptool-js spricht das Board über die Web Serial API an. Du brauchst nur ein USB-Datenkabel und Chrome oder Edge auf einem Desktop-Rechner. Die Seite muss über HTTPS ausgeliefert werden. Du wählst den seriellen Port, und die Firmware wird direkt aus dem Browser geschrieben.

Veroffentlicht

Lust, dein eigenes Gizmo zu bauen?

Such dir ein Open-Source-Projekt mit dem ESP32 aus und folge der Schritt-für-Schritt-Anleitung, von der Teileliste und der Verkabelung bis zur Firmware und zum ersten Start.

Lies auch

Kategorien entdecken