ewt-gen

Generate static websites for ESPHome firmware distribution using ESP Web Tools. Example output.

Quick Start

# From a local file
uvx ewt-gen config.yaml

# From a URL
uvx ewt-gen https://github.com/esphome/firmware/blob/main/esphome-web/esp32.factory.yaml

# Multiple configurations
uvx ewt-gen esp32.yaml esp32c3.yaml

Installation

# Run directly without installing (recommended)
uvx ewt-gen config.yaml

# Or install globally
uv tool install ewt-gen
ewt-gen config.yaml

# Or with pip
pip install ewt-gen

Usage

# From a local file
uvx ewt-gen config.yaml

# From a GitHub file URL
uvx ewt-gen https://github.com/user/repo/blob/main/config.yaml

# From a GitHub Gist
uvx ewt-gen https://gist.github.com/user/abc123

# From any URL
uvx ewt-gen https://example.com/config.yaml

Options

ewt-gen [OPTIONS] YAML_SOURCE

Options:
  --version                       Show version
  --skip-compile                  Skip ESPHome compilation (use existing firmware)
  -f, --firmware PATH             Path to firmware binary
  -c, --chip-family [esp32|esp32-c3|esp32-s2|esp32-s3|esp8266]
                                  Chip family (auto-detected from YAML)
  -o, --output PATH               Output directory (defaults to YAML filename)
  -t, --title TEXT                Page title (defaults to name from YAML)
  --pre-release                   Use pre-release ESPHome version via uvx
  --publish-url TEXT              URL where firmware will be published (enables OTA)
  --fw-version TEXT               Firmware version (read from esphome.project.version if not specified)
  --release-url TEXT              Release notes URL for the manifest OTA entry (auto-detected from the GitHub Actions trigger: release page or triggering commit)
  --release-summary TEXT          Short release summary for the manifest OTA entry
  --help                          Show help

Examples

# Basic usage - compiles and generates site
ewt-gen my-device.yaml

# Custom output directory and title
ewt-gen my-device.yaml -o ./dist -t "My Smart Device"

# Use pre-release ESPHome
ewt-gen my-device.yaml --pre-release

# Skip compilation, use existing firmware
ewt-gen my-device.yaml --skip-compile -f firmware.bin

# Enable OTA updates and dashboard import
ewt-gen my-device.yaml --publish-url https://firmware.example.com/my-device

# Specify version explicitly
ewt-gen my-device.yaml --publish-url https://firmware.example.com/my-device --fw-version 1.0.0

OTA Updates and Dashboard Import

When using --publish-url, the tool generates a factory firmware that includes:

• OTA updates via HTTP - Devices can check for and install firmware updates
• Dashboard import - Users can adopt the device ("Take Control") in ESPHome Dashboard

ESPHome's dashboard import requires a git shorthand URL (github://owner/repo/config.yaml@ref) — a plain published URL is not accepted. The import URL is determined, in order, from:

1. --import-url if provided (e.g. github://user/repo/config.yaml@main)
2. The GitHub source URL, when the config is fetched from one
3. The GitHub Actions context (GITHUB_REPOSITORY, GITHUB_REF_NAME and the config's path in the checkout) when generated by a workflow

If none of these apply, dashboard import is omitted (OTA updates still work).

The tool creates two YAML files in the output:

• {name}.yaml - The original configuration (for users to customize)
• {name}.factory.yaml - Factory firmware that imports the original and adds OTA support

The version is required for OTA updates to work correctly. It can be specified via:

• --fw-version command line option
• esphome.project.version field in the YAML configuration

If no version is found, a warning is shown and OTA components are omitted (dashboard import still works).

When OTA is enabled, each manifest.json build also gets an ota entry that ESPHome's update.http_request platform uses to update already-running devices:

{
  "chipFamily": "ESP32-S3",
  "parts": [{ "path": "firmware-esp32s3-2026.6.0.bin", "offset": 0 }],
  "ota": {
    "path": "firmware-esp32s3-2026.6.0.ota.bin",
    "md5": "...",
    "sha256": "...",
    "summary": "ESPHome 2026.6.0",
    "release_url": "https://github.com/owner/repo/releases/tag/2026.6.0"
  }
}

The OTA (app-only) image is copied alongside the factory image and its checksums are computed automatically. The optional summary and release_url fields, shown by the firmware update entity, are set with:

• --release-summary - short text describing the release
• --release-url - link to the release notes. When not specified and running in GitHub Actions, this is auto-detected from the trigger: the release page for release events, otherwise a link to the triggering commit (since not every workflow publishes a GitHub Release)

Generated Site

The tool generates a static website containing:

• ESP Web Tools install button - One-click firmware installation (requires HTTPS)
• Alternative install section - Link to download binary and use with ESPHome Web
• ESPHome configuration section - Download links and expandable view of the YAML configuration
• Manual installation instructions - For non-HTTPS contexts, with link to web.esphome.io

Configurations with Packages

When a configuration pulls in local packages, the top-level YAML on its own is not enough to build the firmware. In that case the configuration download becomes {name}.esphomebundle.tar.gz, made by esphome bundle. It holds the entry file and every local file it depends on, so ESPHome compiles it as-is:

esphome compile my-device.esphomebundle.tar.gz

Remote packages (github:// shorthand or a url: block) are not bundled: ESPHome fetches those itself. A configuration that pulls in nothing local keeps the plain YAML download.

A bundle holds the secrets the configuration uses, so publish one only for a configuration whose secrets are already public (one kept in a repository, for example). ESPHome prints a warning when the bundle contains secrets.

HTTPS Requirement

Browser-based installation using ESP Web Tools requires a secure context (HTTPS or localhost). When served over HTTP, the page automatically shows manual installation instructions instead.

ESPHome Detection

The tool automatically:

• Detects chip family from the YAML configuration
• Finds compiled firmware in .esphome/build/ directory
• Uses local esphome if available, falls back to uvx esphome

License

Apache 2.0

Credits

• ESP Web Tools - Browser-based firmware installation
• ESPHome - Easy ESP8266/ESP32 firmware configuration
• Open Home Foundation