-
Notifications
You must be signed in to change notification settings - Fork 102
/
index.html
600 lines (589 loc) · 20.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
<!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.4.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/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="https://firmware.esphome.io/esp-web-tools/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>
<a
href="https://sle118.github.io/squeezelite-esp32-installer/"
target="_blank"
class="project"
>
<div class="logo">
<img
src="static/logos/squeezelite-esp32.png"
alt="Squeezelite-ESP32 logo"
/>
</div>
<div class="name">Squeezelite-ESP32</div>
</a>
<a
href="https://2smart.com/docs-resources/platform-updates/platform-updates-13-07-2022"
target="_blank"
class="project"
>
<div class="logo">
<img src="static/logos/2smart.png" alt="2Smart logo" />
</div>
<div class="name">2Smart</div>
</a>
<a href="https://clockwise.page" target="_blank" class="project">
<div class="logo">
<img src="static/logos/clockwise.png" alt="Clockwise logo" />
</div>
<div class="name">Clockwise</div>
</a>
<a
href="https://sblantipodi.github.io/glow_worm_luciferin"
target="_blank"
class="project"
>
<div class="logo">
<img
src="static/logos/luciferin_logo.png"
alt="Firefly Luciferin logo"
/>
</div>
<div class="name">Luciferin</div>
</a>
<a
href="https://install.openepaperlink.de"
target="_blank"
class="project"
>
<div class="logo">
<img
src="static/logos/openepaperlink.png"
alt="OpenEpaperLink logo"
/>
</div>
<div class="name">OpenEpaperLink</div>
</a>
</div>
<h2>How it works</h2>
<p>
ESP Web Tools works by combining
<a href="https://developer.mozilla.org/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@10/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="https://firmware.esphome.io/esp-web-tools/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/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="preparing-firmware">Preparing your firmware</h3>
<p>
If you have ESP32 firmware and are using ESP-IDF framework v4 or later,
you will need to create a merged version of your firmware before being
able to use it with ESP Web Tools. If you use ESP8266 or ESP32 with
ESP-IDF v3 or earlier, you can skip this section.
</p>
<p>
ESP32 firmware is split into 4 different files. When these files are
installed using the command-line tool <code>esptool</code>, it will
patch flash frequency, flash size and flash mode to match the target
device. ESP Web Tools is not able to do this on the fly, so you will
need to use <code>esptool</code> to create the single binary file and
use that with ESP Web Tools.
</p>
<p>
Create a single binary using <code>esptool</code> with the following
command:
</p>
<pre>
esptool --chip esp32 merge_bin \
-o merged-firmware.bin \
--flash_mode dio \
--flash_freq 40m \
--flash_size 4MB \
0x1000 bootloader.bin \
0x8000 partitions.bin \
0xe000 boot.bin \
0x10000 your_app.bin</pre
>
<p>
If your memory type is <code>opi_opi</code> or <code>opi_qspi</code>,
set your flash mode to be <code>dout</code>. Else, if your flash mode is
<code>qio</code> or <code>qout</code>, override your flash mode to be
<code>dio</code>.
</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-C2</code>,
<code>ESP32-C3</code>, <code>ESP32-C6</code>, <code>ESP32-H2</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": "merged-firmware.bin", "offset": 0 },
]
},
{
"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>
<li><code>--esp-tools-button-border-radius</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="https://firmware.esphome.io/esp-web-tools/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>