ESP Web Tools

ESP Web Tools is a set of open source tools to allow working with ESP devices in the browser. The code is available on GitHub.

To try it out and install the ESPHome firmware, connect an ESP to your computer and hit the button:

Note, this only works in desktop Chrome and Edge. Android support should be possible but has not been implemented yet. If you don't see your ESP device, you might miss drivers.

This works by combining Web Serial with a manifest which describes the firmware. It will automatically detect the type of the connected ESP device and find the right firmware files in the manifest.

Projects using ESP Web Tools

WLED

A fast and feature-rich implementation of an ESP8266/ESP32 firmware to control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based chipsets like the WS2801 and APA102.

Installation Website

Adding ESP Web Tools to your website

To add this to your own website, create a manifest and add the button to your website. Make sure you update the manifest attribute to point at your manifest.

You can import ESP Web Tools directly from the unpkg CDN or download the files and put them on your website. 

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

<esp-web-install-button
  manifest="static/firmware_build/manifest.json"
></esp-web-install-button>

Your website needs to be served over https://. If your manifest is hosted on another server, make sure you configure the CORS-headers for your manifest and firmware files such that your website is allowed to fetch those files by adding the header Access-Control-Allow-Origin: https://domain-of-your-website.com.

Add the attribute erase-first if you want to first fully erase the ESP prior to installation.

ESP Web Tools can also be integrated in your projects by installing it via NPM:
npm install --save esp-web-tools

Creating your manifest

ESP Web Tools manifest describe the firmware that you want to install. It allows specifying different builds for the different types of ESP devices. Current supported devices are ESP8266, ESP32 and ESP32-S2. The correct build will be automatically selected based on the type of the ESP device we detect via the serial port. 

{
  "name": "ESPHome",
  "builds": [
    {
      "chipFamily": "ESP32",
      "improv": true,
      "parts": [
        { "path": "bootloader.bin", "offset": 4096 },
        { "path": "partitions.bin", "offset": 32768 },
        { "path": "ota.bin", "offset": 57344 },
        { "path": "firmware.bin", "offset": 65536 }
      ]
    },
    {
      "chipFamily": "ESP8266",
      "parts": [
        { "path": "esp8266.bin", "offset": 0 }
      ]
    }
  ]
}

Each build contains a list of parts to be flashed to the ESP device. Each part consists of a path to the file and an offset on the flash where it should be installed. Part paths are resolved relative to the path of the manifest, but can also be URLs to other hosts.

Each build also allows you to specify if it supports the Improv Wi-Fi standard. If it does, the user will be offered to configure the Wi-Fi after installation is done as can be seen in the video below.

Customizing the look and feel

There are multiple options to change the look and feel of the button and other elements.

Change colors

You can change the colors of the default UI elements with CSS custom properties (variables), the following variables are available:

There are also some attributes that can be used for styling:

install-supported Added if installing firmware is supported
install-unsupported Added if installing firmware is not supported
active Added when flashing is active

When you are using a custom button, you should disable it when the active attribute is present.

Replace the button and message with a custom one

You can replace both the activation button and the message that is shown when the user uses an unsupported browser or non-secure context with your own elements. This can be done using the activate, unsupported and not-allowed slots: 

<esp-web-install-button
  manifest="static/firmware_build/manifest.json"
  show-log
  erase-first
>
  <button slot="activate">Custom install button</button>
  <span slot="unsupported">Ah snap, your browser doesn't work!</span>
  <span slot="not-allowed">Ah snap, you are not allowed to use this on HTTP!</span>
</esp-web-install-button>

Show or hide the progress bar and log

By default there is a progress bar showing the state and progress of the flashing progress, you can change this progress bar to a log view with the show-log attribute.

You can also hide all progress indicators by adding the hide-progress attribute. This will hide both the progress bar and the log view. You can then implement your own progress elements using the state events.

State events

During the flash progress the button will fire state-changed events for every step of the progress and to signal progress in the writing.

With these events you can create your own progress UI or trigger certain actions. You can also find the current state as the state property of the esp-web-install-button element.

Events for the following states are fired:

A state-changed event contains the following information:

state The current state; one of the above
message A description of the current state
manifest The loaded manifest
build The manifest's build that was selected
chipFamily The chip that was detected; "ESP32" | "ESP8266" | "ESP32-S2" | "Unknown Chip"
details An optional extra field that is different per state

An example that logs all state events:

<esp-web-install-button
  manifest="static/firmware_build/manifest.json"
></esp-web-install-button>
<script>
const espWebInstallButton = document.querySelector("esp-web-install-button");
espWebInstallButton.addEventListener(
  "state-changed", (ev) => { console.log(ev.detail) }
);
</script>

USB Serial Drivers

If the serial port is not showing up, your computer might be missing the drivers for the USB serial chip used in your ESP device. These drivers work for most ESP devices:

ESP Web Tools – GitHub
ESP Web Tools is a project by ESPHome.
Development is funded by Nabu Casa.