ESP Web Tools

ESP Web Tools allows you to manage ESP8266 and ESP32 devices in the browser: install new firmware, update firmware, connect device to the Wi-Fi network, visit the device's hosted web interface and add devices to Home Assistant.

ESP Web Tools works by combining Web Serial, Improv Wi-Fi (optional), and a manifest which describes the firmware. It will automatically find the supported firmware files from the manifest by detecting the chipset of the connected ESP device.

Web Serial is available in Google Chrome and Microsoft Edge browsers (but not on your iOS device). Android support should be possible but has not been implemented yet.

Try a live demo

This demo will install ESPHome. To get started, connect an ESP device to your computer and hit the button:

The demo is not available because your browser does not support Web Serial. Open this page in Google Chrome or Microsoft Edge instead (but not on your iOS device).

If you don't see your ESP device in the list of devices to choose, you might need to install the drivers.

Products using ESP Web Tools

Adding ESP Web Tools to your website

To add this to your own website, you need to include the ESP Web Tools JavaScript files on your website, create a manifest file and render the ESP Web Tools button.

You can import the JavaScript files 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@7.1.0/dist/web/install-button.js?module"
></script>

Find a place on your page where you want the button to appear and include the following bit of HTML. Update the manifest attribute to point at your manifest file.

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

ESP Web Tools requires that your website is served over https:// to work. This is a Web Serial security limitation.

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

ESP Web Tools can also be integrated in your projects by installing it via NPM.

Creating your manifest

Manifests describe the firmware that you want to offer the user to install. It allows specifying different builds for the different types of ESP devices. Current supported chip families are ESP8266, ESP32, ESP32-C3 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",
  "version": "2021.11.0",
  "home_assistant_domain": "esphome",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32",
      "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 installed 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.

If your firmware is supported by Home Assistant, you can add the optional key home_assistant_domain. If present, ESP Web Tools will link the user to add this device to Home Assistant.

By default a new installation will erase all data before installation. If you want to leave this choice to the user, set the optional manifest key new_install_prompt_erase to true. ESP Web Tools offers users a new installation if it is unable to detect the current firmware of the device (via Improv Serial) or if the detected firmware does not match the name specififed in the manifest.

When a firmware is first installed on a device, it might need to do some time consuming tasks like initializing the file system. By default ESP Web Tools will wait 10 seconds to receive an Improv Serial response to indicate that the boot is completed. You can increase this timeout by setting the optional manifest key new_install_improv_wait_time to the number of seconds to wait. Set to 0 to disable Improv Serial detection.

Configuring Wi-Fi

ESP Web Tools supports the Improv Wi-Fi serial standard. This is an open standard to allow configuring Wi-Fi via the serial port.

If the firmware supports Improv, a user will be asked to connect the device to the network after installing the firmware. Once connected, the device can send the user to a URL to finish configuration. For example, this can be a link to the device's IP address where it serves a local UI.

At any time in the future a user can use ESP Web Tools to find the device link or to reconfigure the Wi-Fi settings without doing a reinstall.

Screenshot showing the ESP Web Tools interface

Customizing the look and feel

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

• --esp-tools-button-color
• --esp-tools-button-text-color

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

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"
>
  <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>
    

Viewing logs & sending commands

ESP Web Tools allows users to open a serial console to see the logs and send commands.

Screenshot showing the ESP Web Tools logs & console

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:

• CP2102 (square chip): driver
• CH341: driver

Why we created ESP Web Tools