tasmota-esp-web-tools/README.md

Web tools for ESP devices

# ESP Web Tools next generation

Allow flashing Tasmota or other ESP-based firmwares via the browser. Will automatically detect the board type and select a supported firmware. [See website for full documentation.](https://jason2866.github.io/esp-web-tools/))

```html
<esp-web-install-button
  manifest="firmware/manifest.json"
></esp-web-install-button>
```

Example manifest:

```json
{
  "name": "Tasmota",
  "new_install_prompt_erase": true,
  "funding_url": "https://paypal.me/tasmota",
  "new_install_improv_wait_time": 10,
  "builds": [
    {
      "chipFamily": "ESP32",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-C2",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32c2.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-C3",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32c3.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-C5",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32c5.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-C6",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32c6.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-C61",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32c61.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-S2",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32s2.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP32-S3",
      "improv": true,
      "parts": [
        { "path": "../firmware/tasmota32/tasmota32s3.factory.bin", "offset": 0 }
      ]
    },
    {
      "chipFamily": "ESP8266",
      "improv": true,
      "parts": [{ "path": "../firmware/tasmota/tasmota.bin", "offset": 0 }]
    }
  ]
}
```

## Chip Variant Support (ESP32-P4)

For chips with multiple hardware revisions (like ESP32-P4), you can specify different firmware builds for each variant:

```json
{
  "name": "My Firmware",
  "builds": [
    {
      "chipFamily": "ESP32-P4",
      "chipVariant": "rev0",
      "parts": [{ "path": "firmware_p4_old.bin", "offset": 0 }]
    },
    {
      "chipFamily": "ESP32-P4",
      "chipVariant": "rev300",
      "parts": [{ "path": "firmware_p4_new.bin", "offset": 0 }]
    }
  ]
}
```

The `chipVariant` field is optional. If omitted, the build will match any variant of that chip family.

See [manifest-example-p4-variants.json](manifest-example-p4-variants.json) for a complete example.

## Flash Size Support

For chips with different flash sizes, you can specify `flashSizeMB` to target specific hardware configurations. This is useful for ESP32-S3 modules that come with various flash sizes.

```json
{
  "name": "My Firmware",
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "flashSizeMB": 16,
      "parts": [{ "path": "s3-16mb.bin", "offset": 0 }]
    },
    {
      "chipFamily": "ESP32-S3",
      "flashSizeMB": 4,
      "parts": [{ "path": "s3-4mb.bin", "offset": 0 }]
    },
    {
      "chipFamily": "ESP32-S3",
      "parts": [{ "path": "s3-generic.bin", "offset": 0 }]
    }
  ]
}
```

A device with ESP32-S3 and 16MB flash gets the first build, 4MB gets the second, and any other ESP32-S3 falls back to the third.

The `flashSizeMB` field is **optional**. If omitted, the build will match any flash size. Builds with matching `flashSizeMB` are preferred over builds without it (most-specific-matching algorithm).

## USB Interface Support (UART vs CDC)

For chips that can be connected either through a native USB interface (USB-JTAG/USB-OTG, e.g. ESP32-S2/S3/C3/C6/...) or through an external USB-to-Serial bridge (CP210x, FTDI, CH340, ...), you can ship dedicated firmware variants by specifying `usbInterface`:

- `"CDC"` – firmware built for native USB (CDC) console / programming
- `"UART"` – firmware built for the regular UART console via an external USB-to-Serial chip

```json
{
  "name": "My Firmware",
  "builds": [
    {
      "chipFamily": "ESP32-S3",
      "usbInterface": "CDC",
      "parts": [{ "path": "s3-cdc.bin", "offset": 0 }]
    },
    {
      "chipFamily": "ESP32-S3",
      "usbInterface": "UART",
      "parts": [{ "path": "s3-uart.bin", "offset": 0 }]
    }
  ]
}
```

ESP Web Tools automatically detects how the device is connected:

- If the device is reached via native USB (USB-JTAG/USB-OTG) the build with `usbInterface: "CDC"` is selected.
- Otherwise (external USB-to-Serial bridge) the build with `usbInterface: "UART"` is selected.

The `usbInterface` field is **optional**. If omitted, the build will match any USB interface and is used as a fallback. It can also be combined freely with `chipVariant` and `flashSizeMB`.

## Performance

ESP Web Tools supports configurable baud rates for flashing. By default, it uses 115200 baud for maximum compatibility. You can increase the baud rate for significantly faster flashing speeds.

### Custom Baud Rate

You can customize the baud rate using the `baud-rate` attribute:

```html
<!-- Default: 115200 baud (maximum compatibility) -->
<esp-web-install-button manifest="manifest.json">
  <button slot="activate">Install</button>
</esp-web-install-button>

<!-- Fast: 2 Mbps (~17x faster, recommended for modern chips) -->
<esp-web-install-button 
  manifest="manifest.json"
  baud-rate="2000000">
  <button slot="activate">Install</button>
</esp-web-install-button>

<!-- Safe: 460800 baud (~4x faster, works with older USB-Serial chips like CH340) -->
<esp-web-install-button 
  manifest="manifest.json"
  baud-rate="460800">
  <button slot="activate">Install</button>
</esp-web-install-button>
```

Available baud rates: `230400`, `460800`, `921600`, `1500000`, `2000000`

## Development

Run `script/develop`. This starts a server. Open it on http://localhost:5004.