mirror of
https://github.com/esphome/esp-web-tools.git
synced 2025-04-19 21:27:20 +00:00
508 lines
17 KiB
HTML
508 lines
17 KiB
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.3.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@9.0.3/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 & 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="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>
|
|
|
|
<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>
|
|
</div>
|
|
|
|
<h2>How it works</h2>
|
|
<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. 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>
|
|
<script
|
|
type="module"
|
|
src="https://unpkg.com/esp-web-tools@9.0.3/dist/web/install-button.js?module"
|
|
></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>
|
|
<esp-web-install-button
|
|
manifest="/static/firmware_build/manifest.json"
|
|
></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/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>ESP32-C3</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": "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 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><esp-web-install-button></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
|
|
>
|
|
|
|
<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>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>.<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>
|