oleg
/
esp-web-tools
spiegel van https://github.com/esphome/esp-web-tools.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491
							<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 {
        height: 50px;
      }
      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: #000;
      }
      .videoWrapper iframe {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
      }
      .hidden {
        display: none;
      }
      .supported-info {
        display: none;
      }
      esp-web-install-button[install-supported] + .supported-info {
        display: block;
      }
      .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;
      }
      @media (prefers-color-scheme: dark) {
        body {
          background-color: #333;
          color: #fff;
        }
        a {
          color: #58a6ff;
        }
      }
    </style>
    <script module>
      import(
        // In development we import locally.
        window.location.hostname === "localhost"
          ? "/dist/web/install-button.js"
          : "https://unpkg.com/esp-web-tools@5.1.0/dist/web/install-button.js?module"
      );
    </script>
  </head>
  <body>
    <div class="content">
      <h1>ESP Web Tools</h1>
      <p>
        ESP Web Tools allows you to manage ESP8266 and ESP32 devices in the
        browser: install new firmware, update firmware, connect device to the
        Wi-Fi network, visit the device's hosted web interface and add devices
        to <a href="https://www.home-assistant.io">Home Assistant</a>.
      </p>
      <div class="videoWrapper">
        <iframe
          width="560"
          height="315"
          src="https://www.youtube-nocookie.com/embed/E8bdATqXM8c"
          title="YouTube video player"
          frameborder="0"
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
          allowfullscreen
        ></iframe>
      </div>

      <p>
        ESP Web Tools works by combining
        <a
          href="https://developer.mozilla.org/en-US/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. It will automatically find
        the supported firmware files from the manifest by detecting the chipset
        of the connected ESP device.
      </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>

      <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="static/firmware_build/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>
      <p class="supported-info">
        If you don't see your ESP device in the list of devices to choose, you
        might need to install
        <a href="#drivers">the drivers</a>.
      </p>

      <h2 id="used-by">Products 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>
          Fast and feature-rich firmware to control NeoPixel (WS2812B, WS2811,
          SK6812) LEDs and 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="https://tasmota.github.io" class="logo"
          ><img src="static/logos/tasmota.svg" alt="Tasmota logo"
        /></a>
        <h3>Tasmota</h3>
        <p>
          Firmware with easy configuration using webUI, OTA updates, automation
          using timers or rules, expandability and entirely local control over
          MQTT, HTTP, Serial or KNX.
        </p>
        <p>
          <a href="https://arendst.github.io/Tasmota-firmware/" 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>
      <div class="project">
        <a href="https://canair.io" class="logo"
          ><img src="static/logos/canairio.png" alt="CanAirIO logo"
        /></a>
        <h3>CanAirIO</h3>
        <p>
          Citizen science initiative for monitoring air quality. CanAirIO uses
          mobile and fixed sensors to measure air quality with smartphones and
          ESP32 devices.
        </p>
        <p>
          <a href="https://canair.io/installer.html" target="_blank"
            >Installation Website</a
          >
        </p>
      </div>
      <div class="project">
        <a href="https://esphome.io" class="logo"
          ><img src="static/logos/esphome.svg" alt="ESPHome logo"
        /></a>
        <h3>ESPHome</h3>
        <p>
          No-code platform for ESP devices. Uses ESP Web Tools in their
          dashboard to install ESPHome on devices.
        </p>
        <p>
          <a href="https://esphome.io" target="_blank">Website</a>
        </p>
      </div>
      <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 render the
        ESP Web Tools button.
      </p>
      <p>
        You can import the JavaScript files 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@5.1.0/dist/web/install-button.js?module"
>&lt;/script></pre
      >
      <p>
        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="/static/firmware_build/manifest.json"
>&lt;/esp-web-install-button></pre
      >
      <p>
        ESP Web Tools requires that your website is served over
        <code>https://</code> to work. This is a Web Serial security limitation.
      </p>
      <p>
        If your manifest or the firmware files are hosted on another server,
        make sure you configure
        <a href="https://developer.mozilla.org/en-US/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="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>ESP32C3</code> and
        <code>ESP32S2</code>. 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",
  "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 }
      ]
    }
  ]
}</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>
        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 the entire flash. If you want
        to skip this step, set the optional key
        <code>new_install_skip_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>
      <h2 id="improv">Configuring Wi-Fi</h2>
      <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="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>
      </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="/static/firmware_build/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 id="logs">Viewing logs & sending commands</h2>
      <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="drivers">USB Serial Drivers</h2>
      <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>
    <script>
      if (/iPad|iPhone|iPod/.test(navigator.userAgent)) {
        document.querySelector(".not-supported-i").classList.remove("hidden");
      }
    </script>
  </body>
</html>