oleg
/
esp-web-tools
mirror of https://github.com/esphome/esp-web-tools.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463
							<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"
    />
    <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;
      }
      .project .logo {
        float: right;
      }
      .project .logo img {
        max-height: 50px;
      }
      a {
        color: #03a9f4;
      }
      .videoWrapper {
        position: relative;
        padding-bottom: 56.25%; /* 16:9 */
        height: 0;
        margin-bottom: 25px;
        background: #000;
      }
      .videoWrapper iframe {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
      }
      .content pre {
        max-width: 100%;
        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;
      }
    </style>
    <script module>
      import(
        // In development we import locally.
        window.location.hostname === "localhost"
          ? "/dist/web/install-button.js"
          : "https://unpkg.com/esp-web-tools@3.4.0/dist/web/install-button.js?module"
      );
    </script>
  </head>
  <body>
    <div class="content">
      <h1>ESP Web Tools</h1>
      <p>
        ESP Web Tools is a set of open source tools to allow working with ESP
        devices in the browser.
        <a href="https://github.com/esphome/esp-web-tools"
          >The code is available on GitHub.</a
        >
      </p>
      <p>
        To try it out and install
        <a href="https://esphome.io">the ESPHome firmware</a>, connect an ESP to
        your computer and hit the button:
      </p>
      <esp-web-install-button
        erase-first
        manifest="static/firmware_build/manifest.json"
      ></esp-web-install-button>
      <p>
        <i>
          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 <a href="#drivers">drivers</a>.
        </i>
      </p>
      <p>
        This works by combining
        <a
          href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API"
          >Web Serial</a
        >
        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.
      </p>
      <div class="videoWrapper">
        <iframe
          width="560"
          height="315"
          src="https://www.youtube-nocookie.com/embed/k88BS8zgWq0"
          title="YouTube video player"
          frameborder="0"
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
          allowfullscreen
        ></iframe>
      </div>
      <h2 id="used-by">Projects using ESP Web Tools</h2>
      <div class="project">
        <a href="https://wled.me" class="logo"
          ><img src="static/logos/wled.png" alt="WLED logo"
        /></a>
        <h3>WLED</h3>
        <p>
          A fast and feature-rich implementation of an ESP8266/ESP32 firmware to
          control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based
          chipsets like the WS2801 and APA102.
        </p>
        <p>
          <a href="https://install.wled.me" target="_blank"
            >Installation Website</a
          >
        </p>
      </div>
      <div class="project">
        <a href="http://www.espeasy.com/" class="logo"
          ><img src="static/logos/espeasy.png" alt="ESPEasy logo"
        /></a>
        <h3>ESPEasy</h3>
        <p>Easy MultiSensor device based on ESP8266/ESP32.</p>
        <p>
          <a href="https://td-er.nl/ESPEasy/" target="_blank"
            >Installation Website</a
          >
        </p>
      </div>
      <h2 id="add-website">Adding ESP Web Tools to your website</h2>
      <p>
        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.
      </p>
      <p>
        You can import ESP Web Tools directly from the unpkg CDN or
        <a href="https://unpkg.com/browse/esp-web-tools/dist/web/"
          >download the files</a
        >
        and put them on your website.
      </p>
      <pre>
&lt;script
  type="module"
  src="https://unpkg.com/esp-web-tools@3.4.0/dist/web/install-button.js?module"
>&lt;/script>

&lt;esp-web-install-button
  manifest="static/firmware_build/manifest.json"
>&lt;/esp-web-install-button></pre
      >
      <p>
        Your website needs to be served over <code>https://</code>. If your
        manifest is hosted on another server, make sure you configure
        <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"
          >the CORS-headers</a
        >
        for your manifest and firmware files 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>
        Add the attribute <code>erase-first</code> if you want to first fully
        erase the ESP prior to installation.
      </p>
      <p>
        ESP Web Tools can also be integrated in your projects by installing it
        via NPM:<br />
        <code>npm install --save esp-web-tools</code>
      </p>
      <h3 id="manifest">Creating your manifest</h3>
      <p>
        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 devices are ESP8266, ESP32 and ESP32-S2. The
        correct build will be automatically selected based on the type of the
        ESP device we detect via the serial port.
      </p>
      <pre>
{
  "name": "ESPHome",
  "builds": [
    {
      "chipFamily": "ESP32",
      "improv": true,
      "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 }
      ]
    }
  ]
}</pre
      >
      <p>
        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.
      </p>
      <p>
        Each build also allows you to specify if it supports
        <a href="https://www.improv-wifi.com">the Improv Wi-Fi standard</a>. If
        it does, the user will be offered to configure the Wi-Fi after
        installation is done as can be seen in the video below.
      </p>
      <div class="videoWrapper">
        <iframe
          width="560"
          height="315"
          src="https://www.youtube-nocookie.com/embed/k88BS8zgWq0?start=33"
          title="YouTube video player"
          frameborder="0"
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
          allowfullscreen
        ></iframe>
      </div>

      <h3 id="customize">Customizing the look and feel</h3>
      <p>
        There are multiple options to change the look and feel of the button and
        other elements.
      </p>
      <h4>Change colors</h4>
      <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-success-color</code></li>
        <li><code>--esp-tools-error-color</code></li>

        <li><code>--esp-tools-progress-color</code></li>

        <li><code>--esp-tools-log-background</code></li>
        <li><code>--esp-tools-log-text-color</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>
        <tr>
          <td><code>active</code></td>
          <td>Added when flashing is active</td>
        </tr>
      </table>
      <p>
        When you are using a custom button, you should disable it when the
        <code>active</code> attribute is present.
      </p>
      <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="static/firmware_build/manifest.json"
  show-log
  erase-first
>
  &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
      >
      <h4>Show or hide the progress bar and log</h4>
      <p>
        By default there is a progress bar showing the state and progress of the
        flashing progress, you can change this progress bar to a log view with
        the <code>show-log</code> attribute.
      </p>
      <p>
        You can also hide all progress indicators by adding the
        <code>hide-progress</code>
        attribute. This will hide both the progress bar and the log view. You
        can then implement your own progress elements using the
        <a href="#state-events">state events</a>.
      </p>

      <h3 id="state-events">State events</h3>
      <p>
        During the flash progress the button will fire
        <code>state-changed</code> events for every step of the progress and to
        signal progress in the writing.
      </p>
      <p>
        With these events you can create your own progress UI or trigger certain
        actions. You can also find the current state as the
        <code>state</code> property of the
        <code>esp-web-install-button</code> element.
      </p>
      <p>Events for the following states are fired:</p>
      <ul>
        <li>initializing</li>
        <li>manifest</li>
        <li>preparing</li>
        <li>erasing</li>
        <li>writing</li>
        <li>finished</li>
        <li>error</li>
      </ul>
      <p>
        A <code>state-changed</code> event contains the following information:
      </p>
      <table>
        <tr>
          <td><code>state</code></td>
          <td>The current state; one of the above</td>
        </tr>
        <tr>
          <td><code>message</code></td>
          <td>A description of the current state</td>
        </tr>
        <tr>
          <td><code>manifest</code></td>
          <td>The loaded manifest</td>
        </tr>
        <tr>
          <td><code>build</code></td>
          <td>The manifest's build that was selected</td>
        </tr>
        <tr>
          <td><code>chipFamily</code></td>
          <td>
            The chip that was detected;
            <code>"ESP32" | "ESP8266" | "ESP32-S2" | "Unknown Chip"</code>
          </td>
        </tr>
        <tr>
          <td><code>details</code></td>
          <td>
            An optional extra field that is different
            <a
              href="https://github.com/esphome/esp-web-tools/blob/main/src/const.ts"
              >per state</a
            >
          </td>
        </tr>
      </table>
      <p>An example that logs all state events:</p>
      <pre>
&lt;esp-web-install-button
  manifest="static/firmware_build/manifest.json"
>&lt;/esp-web-install-button>
&lt;script>
const espWebInstallButton = document.querySelector("esp-web-install-button");
espWebInstallButton.addEventListener(
  "state-changed", (ev) => { console.log(ev.detail) }
);
&lt;/script>
      </pre>
      <h3 id="drivers">USB Serial Drivers</h3>
      <p>
        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:
      </p>
      <ul>
        <li>
          CP2102 (square chip):
          <a
            href="https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers"
            >driver</a
          >
        </li>
        <li>
          CH341:
          <a
            href="https://github.com/nodemcu/nodemcu-devkit/tree/master/Drivers"
            >driver</a
          >
        </li>
      </ul>
      <div class="footer">
        <div>
          ESP Web Tools –
          <a href="https://github.com/esphome/esp-web-tools">GitHub</a>
        </div>
        <div class="initiative">
          ESP Web Tools is a project by
          <a href="https://esphome.io">ESPHome</a>.<br />
          Development is funded by
          <a href="https://www.nabucasa.com">Nabu Casa</a>.
        </div>
      </div>
    </div>
  </body>
</html>