mirror of
https://github.com/esphome/esp-web-tools.git
synced 2025-04-19 21:27:20 +00:00
482 lines
15 KiB
HTML
482 lines
15 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"
|
||
/>
|
||
<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;
|
||
}
|
||
.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.6.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
|
||
log-console
|
||
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="https://tasmota.github.io" class="logo"
|
||
><img src="static/logos/tasmota.svg" alt="Tasmota logo"
|
||
/></a>
|
||
<h3>Tasmota</h3>
|
||
<p>
|
||
Alternative firmware for ESP8266 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>
|
||
<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>
|
||
<script
|
||
type="module"
|
||
src="https://unpkg.com/esp-web-tools@3.6.0/dist/web/install-button.js?module"
|
||
></script>
|
||
|
||
<esp-web-install-button
|
||
manifest="static/firmware_build/manifest.json"
|
||
></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 chip families are <code>ESP8266</code>,
|
||
<code>ESP32</code>, <code>ESP32-C3</code> and <code>ESP32-S2</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",
|
||
"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>
|
||
<esp-web-install-button
|
||
manifest="static/firmware_build/manifest.json"
|
||
show-log
|
||
erase-first
|
||
>
|
||
<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
|
||
>
|
||
<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>
|
||
<esp-web-install-button
|
||
manifest="static/firmware_build/manifest.json"
|
||
></esp-web-install-button>
|
||
<script>
|
||
const espWebInstallButton = document.querySelector("esp-web-install-button");
|
||
espWebInstallButton.addEventListener(
|
||
"state-changed", (ev) => { console.log(ev.detail) }
|
||
);
|
||
</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>
|