index.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>ESP Web Tools</title>
    <meta
      name="description"
      content="Easily allow users to flash new firmware for their ESP-devices on the web."
    />
    <meta name="viewport" content="width=device-width" />

    <meta property="og:title" content="ESP Web Tools" />
    <meta property="og:site_name" content="ESP Web Tools" />
    <meta
      property="og:url"
      content="https://esphome.github.io/esp-web-tools/"
    />
    <meta property="og:type" content="website" />
    <meta
      property="og:description"
      content="Easily allow users to flash new firmware for their ESP-devices on the web."
    />
    <meta
      property="og:image"
      content="https://esphome.github.io/esp-web-tools/static/social.png"
    />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="ESP Web Tools" />
    <meta
      name="twitter:description"
      content="Easily allow users to flash new firmware for their ESP-devices on the web."
    />
    <meta
      name="twitter:image"
      content="https://esphome.github.io/esp-web-tools/static/social.png"
    />
    <meta name="color-scheme" content="dark light" />
    <style>
      body {
        font-family: -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI",
          Roboto, Ubuntu, sans-serif;
        padding: 0;
        margin: 0;
        line-height: 1.4;
      }
      .content {
        max-width: 600px;
        margin: 0 auto;
        padding: 12px;
      }
      h2 {
        margin-top: 2em;
      }
      h3 {
        margin-top: 1.5em;
      }
      .projects {
        display: flex;
        text-align: center;
        flex-wrap: wrap;
        gap: 24px;
        justify-content: center;
      }
      .projects a {
        color: initial;
        text-decoration: none;
      }
      .project .logo img {
        height: 50px;
      }
      .project .name {
        margin-top: 8px;
      }
      a {
        color: #03a9f4;
      }
      .screenshot {
        text-align: center;
      }
      .screenshot img {
        max-width: 100%;
        box-shadow:
          rgb(0 0 0 / 20%) 0px 2px 1px -1px,
          rgb(0 0 0 / 14%) 0px 1px 1px 0px,
          rgb(0 0 0 / 12%) 0px 1px 3px 0px;
        border-radius: 4px;
      }
      .screenshot i {
        margin-top: 4px;
        display: block;
      }
      .videoWrapper {
        position: relative;
        padding-bottom: 56.25%; /* 16:9 */
        height: 0;
        margin-bottom: 25px;
        background: #ccc;
      }
      .hidden {
        display: none;
      }
      .content pre {
        display: block;
        padding-left: 8px;
        overflow-y: scroll;
      }
      .footer {
        margin-top: 24px;
        border-top: 1px solid #ccc;
        padding-top: 24px;
        text-align: center;
      }
      .footer .initiative {
        font-style: italic;
        margin-top: 16px;
      }
      table {
        border-spacing: 0;
      }
      td {
        padding: 8px;
        border-bottom: 1px solid #ccc;
      }
      @media (prefers-color-scheme: dark) {
        body {
          background-color: #333;
          color: #fff;
        }
        a {
          color: #58a6ff;
        }
      }
    </style>
    <script
      type="module"
      src="https://unpkg.com/@justinribeiro/lite-youtube@1.4.0/lite-youtube.js"
    ></script>
    <script module>
      import(
        // In development we import locally.
        window.location.hostname === "localhost"
          ? "/dist/web/install-button.js"
          : "https://unpkg.com/esp-web-tools/dist/web/install-button.js?module"
      );
    </script>
  </head>
  <body>
    <div class="content">
      <h1>ESP Web Tools</h1>
      <p>
        User friendly tools to manage ESP8266 and ESP32 devices in the browser:
      </p>
      <ul>
        <li>Install &amp; update firmware</li>
        <li>Connect device to the Wi-Fi network</li>
        <li>Visit the device's hosted web interface</li>
        <li>Access logs and send terminal commands</li>
        <li>
          Add devices to
          <a href="https://www.home-assistant.io">Home Assistant</a>
        </li>
      </ul>
      <div class="videoWrapper">
        <lite-youtube
          videoid="E8bdATqXM8c"
          videotitle="ESP Web Tools in action"
        ></lite-youtube>
      </div>

      <h2 id="demo">Try a live demo</h2>
      <p>
        This demo will install
        <a href="https://esphome.io">ESPHome</a>. To get started, connect an ESP
        device to your computer and hit the button:
      </p>
      <esp-web-install-button
        manifest="https://firmware.esphome.io/esp-web-tools/manifest.json"
      >
        <i slot="unsupported">
          The demo is not available because your browser does not support Web
          Serial. Open this page in Google Chrome or Microsoft Edge instead<span
            class="not-supported-i hidden"
          >
            (but not on your iOS device)</span
          >.
        </i>
      </esp-web-install-button>

      <h2 id="used-by">Products using ESP Web Tools</h2>
      <div class="projects">
        <a href="https://install.wled.me" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/wled.png" alt="WLED logo" />
          </div>
          <div class="name">WLED</div>
        </a>
        <a
          href="https://arendst.github.io/Tasmota-firmware/"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img src="static/logos/tasmota.svg" alt="Tasmota logo" />
          </div>
          <div class="name">Tasmota</div>
        </a>
        <a href="https://td-er.nl/ESPEasy/" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/espeasy.png" alt="ESPEasy logo" />
          </div>
          <div class="name">ESPEasy</div>
        </a>
        <a
          href="https://canair.io/installer.html"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img src="static/logos/canairio.png" alt="CanAirIO logo" />
          </div>
          <div class="name">CanAirIO</div>
        </a>
        <a href="https://web.esphome.io" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/esphome.svg" alt="ESPHome logo" />
          </div>
          <div class="name">ESPHome</div>
        </a>
        <a
          href="https://sle118.github.io/squeezelite-esp32-installer/"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img
              src="static/logos/squeezelite-esp32.png"
              alt="Squeezelite-ESP32 logo"
            />
          </div>
          <div class="name">Squeezelite-ESP32</div>
        </a>
        <a
          href="https://2smart.com/docs-resources/platform-updates/platform-updates-13-07-2022"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img src="static/logos/2smart.png" alt="2Smart logo" />
          </div>
          <div class="name">2Smart</div>
        </a>
        <a href="https://clockwise.page" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/clockwise.png" alt="Clockwise logo" />
          </div>
          <div class="name">Clockwise</div>
        </a>
        <a
          href="https://sblantipodi.github.io/glow_worm_luciferin"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img
              src="static/logos/luciferin_logo.png"
              alt="Firefly Luciferin logo"
            />
          </div>
          <div class="name">Luciferin</div>
        </a>
        <a
          href="https://install.openepaperlink.de"
          target="_blank"
          class="project"
        >
          <div class="logo">
            <img
              src="static/logos/openepaperlink.png"
              alt="OpenEpaperLink logo"
            />
          </div>
          <div class="name">OpenEpaperLink</div>
        </a>
        <a href="https://openspool.io" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/openspool.png" alt="OpenSpool logo" />
          </div>
          <div class="name">OpenSpool</div>
        </a>
        <a href="https://usetrmnl.com/flash" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/trmnl.png" alt="TRMNL logo" />
          </div>
          <div class="name">TRMNL</div>
        </a>
        <a href="https://nspanelmanager.com" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/nspanelmanager.svg" alt="NSPanelManager logo" />
          </div>
          <div class="name">NSPanel Manager</div>
        </a>
        <a href="https://github.com/blak3r/treadspan" target="_blank" class="project">
          <div class="logo">
            <img src="static/logos/treadspan.png" alt="Treadspan logo" />
          </div>
          <div class="name">TreadSpan</div>
        </a>
      </div>

      <h2>How it works</h2>
      <p>
        ESP Web Tools works by combining
        <a href="https://developer.mozilla.org/docs/Web/API/Web_Serial_API"
          >Web Serial</a
        >, <a href="https://www.improv-wifi.com/">Improv Wi-Fi</a> (optional),
        and a manifest which describes the firmware. ESP Web Tools detects the
        chipset of the connected ESP device and automatically selects the right
        firmware variant from the manifest.
      </p>
      <p>
        Web Serial is available in Google Chrome and Microsoft Edge
        browsers<span class="not-supported-i hidden">
          (but not on your iOS device)</span
        >. Android support should be possible but has not been implemented yet.
      </p>

      <h3 id="improv">Configuring Wi-Fi</h3>
      <p>
        ESP Web Tools supports the
        <a href="https://www.improv-wifi.com/serial"
          >Improv Wi-Fi serial standard</a
        >. This is an open standard to allow configuring Wi-Fi via the serial
        port.
      </p>
      <p>
        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.
      </p>
      <p>
        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.
      </p>
      <p class="screenshot">
        <img
          src="./static/screenshots/dashboard.png"
          alt="Screenshot showing ESP Web Tools dialog offering visting the device, adding it to Home Assistant, change Wi-Fi, show logs and console and reset data."
        />
        <i>Screenshot showing the ESP Web Tools interface</i>
      </p>

      <h3 id="logs">Viewing logs & sending commands</h3>
      <p>
        ESP Web Tools allows users to open a serial console to see the logs and
        send commands.
      </p>
      <p class="screenshot">
        <img
          src="./static/screenshots/logs.png"
          alt="Screenshot showing ESP Web Tools dialog with a console showing ESPHome logs and a terminal prompt to sent commands."
        />
        <i>Screenshot showing the ESP Web Tools logs & console</i>
      </p>

      <h2 id="add-website">Adding ESP Web Tools to your website</h2>
      <p>
        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 add the ESP
        Web Tools button HTML.
      </p>
      <p>
        <a href="https://github.com/balloob/squeezelite-esp32-install"
          >Click here to see a full example.</a
        >
      </p>
      <p>
        <b>Step 1:</b> Load ESP Web Tools JavaScript on your website by adding
        the following HTML snippet.
      </p>
      <pre>
&lt;script
  type="module"
  src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module"
>&lt;/script></pre
      >
      <p>
        (If you prefer to locally host the JavaScript,
        <a href="https://unpkg.com/browse/esp-web-tools/dist/web/"
          >download it here</a
        >)
      </p>
      <p>
        <b>Step 2:</b> Find a place on your page where you want the button to
        appear and include the following bit of HTML. Update the
        <code>manifest</code> attribute to point at your manifest file.
      </p>
      <pre>
&lt;esp-web-install-button
  manifest="https://firmware.esphome.io/esp-web-tools/manifest.json"
>&lt;/esp-web-install-button></pre
      >
      <p>
        <b>Note:</b> ESP Web Tools requires that your website is served over
        <code>https://</code> to work. This is a Web Serial security
        requirement.
      </p>
      <p>
        If your manifest or the firmware files are hosted on another server,
        make sure you configure
        <a href="https://developer.mozilla.org/docs/Web/HTTP/CORS"
          >the CORS-headers</a
        >
        such that your website is allowed to fetch those files by adding the
        header
        <code
          >Access-Control-Allow-Origin: https://domain-of-your-website.com</code
        >.
      </p>

      <p>
        ESP Web Tools can also be integrated in your projects by installing it
        <a href="https://www.npmjs.com/package/esp-web-tools">via NPM</a>.
      </p>
      <h3 id="preparing-firmware">Preparing your firmware</h3>
      <p>
        If you have ESP32 firmware and are using ESP-IDF framework v4 or later,
        you will need to create a merged version of your firmware before being
        able to use it with ESP Web Tools. If you use ESP8266 or ESP32 with
        ESP-IDF v3 or earlier, you can skip this section.
      </p>
      <p>
        ESP32 firmware is split into 4 different files. When these files are
        installed using the command-line tool <code>esptool</code>, it will
        patch flash frequency, flash size and flash mode to match the target
        device. ESP Web Tools is not able to do this on the fly, so you will
        need to use <code>esptool</code> to create the single binary file and
        use that with ESP Web Tools.
      </p>
      <p>
        Create a single binary using <code>esptool</code> with the following
        command:
      </p>
      <pre>
esptool --chip esp32 merge_bin \
  -o merged-firmware.bin \
  --flash_mode dio \
  --flash_freq 40m \
  --flash_size 4MB \
  0x1000 bootloader.bin \
  0x8000 partitions.bin \
  0xe000 boot.bin \
  0x10000 your_app.bin</pre
      >
      <p>
        If your memory type is <code>opi_opi</code> or <code>opi_qspi</code>,
        set your flash mode to be <code>dout</code>. Else, if your flash mode is
        <code>qio</code> or <code>qout</code>, override your flash mode to be
        <code>dio</code>.
      </p>
      <h3 id="manifest">Creating your manifest</h3>
      <p>
        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
        <code>ESP8266</code>, <code>ESP32</code>, <code>ESP32-C2</code>,
        <code>ESP32-C3</code>, <code>ESP32-C6</code>, <code>ESP32-H2</code>,
        <code>ESP32-S2</code> and <code>ESP32-S3</code>. The correct build will
        be automatically selected based on the type of the connected ESP device.
      </p>
      <pre>
{
  "name": "ESPHome",
  "version": "2021.11.0",
  "home_assistant_domain": "esphome",
  "funding_url": "https://esphome.io/guides/supporters.html",
  "new_install_prompt_erase": false,
  "builds": [
    {
      "chipFamily": "ESP32",
      "parts": [
        { "path": "merged-firmware.bin", "offset": 0 },
      ]
    },
    {
      "chipFamily": "ESP8266",
      "parts": [
        { "path": "esp8266.bin", "offset": 0 }
      ]
    }
  ]
}</pre
      >
      <p>
        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.
      </p>
      <p>
        If your firmware is supported by Home Assistant, you can add the
        optional key <code>home_assistant_domain</code>. If present, ESP Web
        Tools will link the user to add this device to Home Assistant.
      </p>
      <p>
        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
        <code>new_install_prompt_erase</code> to <code>true</code>. 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.
      </p>
      <p>
        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
        <code>new_install_improv_wait_time</code> to the number of seconds to
        wait. Set to <code>0</code> to disable Improv Serial detection.
      </p>
      <p>
        If your product accepts donations you can add
        <code>funding_url</code> to your manifest. This allows you to link to
        your page explaining the user how they can fund development. This link
        is visible in the ESP Web Tools menu when connected to a device running
        your firmware (as detected via Improv).
      </p>
      <p>
        ESP Web Tools allows you to provide your own check if the device is
        running the same firmware as specified in the manifest. This check can
        be setting the <code>overrides</code> property on
        <code>&lt;esp-web-install-button&gt;</code>. The value is an object
        containing a
        <code>checkSameFirmware(manifest, improvInfo)</code> function. The
        <code>manifest</code> parameter is your manifest and
        <code>improvInfo</code> is the information returned from Improv:
        <code>{ name, firmware, version, chipFamily }</code>. This check is only
        called if the device firmware was detected via Improv.
      </p>
      <pre>
const button = document.querySelector('esp-web-install-button');
button.overrides = {
  checkSameFirmware(manifest, improvInfo) {
    const manifestFirmware = manifest.name.toLowerCase();
    const deviceFirmware = improvInfo.firmware.toLowerCase();
    return manifestFirmware.includes(deviceFirmware);
  }
};</pre
      >

      <h4>Generating a manifest dynamically &amp; version management</h4>
      <p>
        Alternatively to a static manifest JSON file, you can generate a Blob URL of a JSON object using <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static"><code>URL.createObjectURL</code></a> to use as the manifest url. This can be useful in situations where you have many firmware bin files, e.g. previous software versions, where you don't want to have a different static manifest json file for each bin. If you are hosting on github.io, this can be paired nicely with <a href="https://docs.github.com/en/rest/repos/contents?apiVersion=2022-11-28#get-contents">github's REST API</a> to view all the bin files inside a folder.
      </p>
      <pre>
const manifest = {
    "name": name,
    "version": version,
    "funding_url": funding_url,
    "new_install_prompt_erase": true,
    "builds": [
        {
            "chipFamily": "ESP32",
            "improv": false,
            "parts": [
                { "path": dependenciesDir+"bootloader.bin", "offset": 4096 },
                { "path": dependenciesDir+"partitions.bin", "offset": 32768 },
                { "path": dependenciesDir+"boot_app0.bin", "offset": 57344 },
                { "path": firmwareFile, "offset": 65536 }
            ]
        }
    ]
}

const json = JSON.stringify(manifest);
const blob = new Blob([json], {type: "application/json"});
document.querySelector("esp-web-install-button").manifest = URL.createObjectURL(blob);
      </pre>

      <h3 id="customize">Customizing the look and feel</h3>
      <p>
        You can change the colors of the default UI elements with CSS custom
        properties (variables), the following variables are available:
      </p>
      <ul>
        <li><code>--esp-tools-button-color</code></li>
        <li><code>--esp-tools-button-text-color</code></li>
        <li><code>--esp-tools-button-border-radius</code></li>
      </ul>
      <p>There are also some attributes that can be used for styling:</p>
      <table>
        <tr>
          <td><code>install-supported</code></td>
          <td>Added if installing firmware is supported</td>
        </tr>
        <tr>
          <td>
            <code>install-unsupported</code>
          </td>
          <td>Added if installing firmware is not supported</td>
        </tr>
      </table>
      <h4>Replace the button and message with a custom one</h4>
      <p>
        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 <code>activate</code>,
        <code>unsupported</code> and <code>not-allowed</code> slots:
      </p>
      <pre>
&lt;esp-web-install-button
  manifest="https://firmware.esphome.io/esp-web-tools/manifest.json"
>
  &lt;button slot="activate">Custom install button&lt;/button>
  &lt;span slot="unsupported">Ah snap, your browser doesn't work!&lt;/span>
  &lt;span slot="not-allowed">Ah snap, you are not allowed to use this on HTTP!&lt;/span>
&lt;/esp-web-install-button>
    </pre
      >

      <h2>Why we created ESP Web Tools</h2>
      <div class="videoWrapper">
        <lite-youtube
          videoid="6ZMXE5PXPqU"
          videotitle="Why we created ESP Web Tools"
          videoStartAt="1255"
        ></lite-youtube>
      </div>

      <div class="footer">
        <div class="initiative">
          ESP Web Tools is a project by
          <a href="https://esphome.io">ESPHome</a>,
          <a href="https://www.openhomefoundation.org">Open Home Foundation</a
          >.<br />
          Development is funded by
          <a href="https://www.nabucasa.com">Nabu Casa</a>.
        </div>
        <div>
          ESP Web Tools is
          <a href="https://github.com/esphome/esp-web-tools">open source</a>.
        </div>
      </div>
    </div>
    <script>
      if (/iPad|iPhone|iPod/.test(navigator.userAgent)) {
        document.querySelector(".not-supported-i").classList.remove("hidden");
      }
    </script>
  </body>
</html>