mirror of
https://github.com/esphome/esp-web-tools.git
synced 2025-04-19 21:27:20 +00:00
493 lines
16 KiB
HTML
493 lines
16 KiB
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;
|
||
}
|
||
.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.2.1/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>
|
||
<script
|
||
type="module"
|
||
src="https://unpkg.com/esp-web-tools@5.2.1/dist/web/install-button.js?module"
|
||
></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>
|
||
<esp-web-install-button
|
||
manifest="/static/firmware_build/manifest.json"
|
||
></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>
|
||
<esp-web-install-button
|
||
manifest="/static/firmware_build/manifest.json"
|
||
>
|
||
<button slot="activate">Custom install button</button>
|
||
<span slot="unsupported">Ah snap, your browser doesn't work!</span>
|
||
<span slot="not-allowed">Ah snap, you are not allowed to use this on HTTP!</span>
|
||
</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>
|