mirror of
https://github.com/esphome/esp-web-tools.git
synced 2025-04-19 21:27:20 +00:00
498 lines
17 KiB
HTML
498 lines
17 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;
|
||
}
|
||
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 {
|
||
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
|
||
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@7.5.0/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>
|
||
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@7.5.0/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
|
||
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>checkSameFirmwareVersion(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 = {
|
||
checkSameFirmwareVersion(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>
|
||
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>
|