# ESP Web Tools
Easily allow users to flash new firmware for their ESP-devices on the web.

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 ESPHome on an ESP, connect it 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.

## Products using ESP Web Tools

### WLED

Fast and feature-rich firmware to control NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI based chipsets like the WS2801 and APA102.

Installation Website

### Tasmota

Firmware with easy configuration using webUI, OTA updates, automation using timers or rules, expandability and entirely local control over MQTT, HTTP, Serial or KNX.

Installation Website

### ESPEasy

Easy MultiSensor device based on ESP8266/ESP32.

Installation Website

### ESPHome

No-code platform for ESP devices. Uses ESP Web Tools in their dashboard to install ESPHome on devices.

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@4.0.2/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`.

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 chip families are `ESP8266`, `ESP32`, `ESP32C3` and `ESP32S2`. 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_skip_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 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.

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 the entire flash. If you want to skip this step, set the optional key `new_install_skip_erase` to `true`. ESP Web Tools considers it 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.

### Wi-Fi provisioning

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

If Improv is supported, a user will be guided to connect the device to the network after installation. It also allows the user to connect already installed devices and re-configure the wireless network settings.

### 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:

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

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