A guide for setting up flashing your ESP projects directly from your browser
ESP-Web-Tools allows your to flash your ESP directly from your browser using Web Serial API. This repo will provide the instructions needed to get this up and running.
You should note that the Web Serial API has some requirements:
- Limited browser support - Basically just Chrome and Edge.
- Website requires https - For this example we will use github pages to host the site, which supports https and is free.
You should also note that the sketchs that are uploaded will have to be generic ones, so can't have configurations like WiFi details so please use something like WiFiManager to solve this, or you can use Improv Wifi
I have put a lot of effort into creating Arduino libraries that I hope people can make use of. If you enjoy my work, please consider becoming a Github sponsor!
Github Pages is a feature of github that allows you to create a static website for your projects. It's free and quite easy to setup. This isn't a full guide for Github pages, but just shows how to configure it for this use case. When you create a github pages site for your project it will live under USER_NAME.github.io/REPO_NAME, so for example the URL for this repo would be witnessmenow.github.io/ESP-Web-Tools-Tutorial
- Click
Settingson the repo you want to add the website to and scroll down to theGitHub Pagessection - Under
Source, change the drop down to yourmainbranch (could bemasterif it's an older repo)
And that's it! when you visit USER_NAME.github.io/REPO_NAME you should see your projects readme converted to a webpage.
Note: I would test this out with a new dummy repo before adding it to your project.
- In your Github repo, create a new file on the root,
flash.html - Populate the file with the following (you can find more details on the ESP-Web-tools page):
<!DOCTYPE html>
<html>
<body>
<h1>ESP-Web-Tool-Test</h1>
<script type="module" src="https://unpkg.com/[email protected]/dist/web/install-button.js?module"></script>
<esp-web-install-button manifest="test/manifest.json"></esp-web-install-button>
</body>
</html>
- In your repo, create a
testfolder - In the
testfolder, create amanifest.jsonfile. - This is the example manifest.json that ESP-Web-Tools provide, you can add that for now:
{
"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 }
]
}
]
}
- You can update the
namefield for your project. - From the example you can see it supports different arcitechures, it will automatically select the appropriate one based on the device thats plugged in. For now remove the entry for the chip you will not be using. (make sure to remove the
,too!) - If you are using the ESP32, set the
improvfield tofalse
This was actually the part I found the hardest, just because I was completely unfamilar what happens once you cick "Upload"!
NOTE: Only the bin files under the temporary Arduino folder will change when you update the sketch, you can re-use the other ones.
- In the Arduino IDE, click File -> Preferences
- Under Show Verbose Ouput, check the Upload option.
- Program your board with the project you want to create the flasher for.
- In the logs scroll up to top , there should be a line with esptool, mine looked like this:
/Users/brian/Library/Arduino15/packages/esp32/tools/esptool_py/3.0.0/esptool --chip esp32
--port /dev/cu.SLAB_USBtoUART --baud 921600 --before default_reset --after hard_reset write_flash
-z --flash_mode dio --flash_freq 80m --flash_size detect
0xe000 /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/partitions/boot_app0.bin
0x1000 /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/sdk/bin/bootloader_qio_80m.bin
0x10000 /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.bin
0x8000 /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.partitions.bin
- This particular example contains 4 bin files and their offsets. The offset comes before the bin address, so the 4 above looks like this extracted out
| Offset(hex) | Bin Location |
|---|---|
| 0xe000 | /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/partitions/boot_app0.bin |
| 0x1000 | /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/sdk/bin/bootloader_qio_80m.bin |
| 0x10000 | /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.bin |
| 0x8000 | /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.partitions.bin |
- The Manifest file expexts the offset in decimal, so convert the hex to decimal
| Offset(hex) | Offset(decimal) | Bin Location |
|---|---|---|
| 0xe000 | 57344 | /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/partitions/boot_app0.bin |
| 0x1000 | 4096 | /Users/brian/Library/Arduino15/packages/esp32/hardware/esp32/1.0.6/tools/sdk/bin/bootloader_qio_80m.bin |
| 0x10000 | 65536 | /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.bin |
| 0x8000 | 32768 | /var/folders/tn/lk3_b69x7kg06xgj6tc4x2000000gn/T/arduino_build_379859/BlinkREgular.ino.partitions.bin |
This is untested by me, but it looks right
- Copy each of the bin files from the previous step to the
testfolder we created earlier (so it should be beside themanifest.json) - Add an entry in
partsfor each bin file using the file name as thepathand the deimal offset foroffset. The above example would look like this:
{
"name": "WebToolTest",
"builds": [
{
"chipFamily": "ESP32",
"improv": false,
"parts": [
{ "path": "bootloader_qio_80m.bin", "offset": 4096 },
{ "path": "BlinkREgular.ino.partitions.bin", "offset": 32768 },
{ "path": "boot_app0.bin", "offset": 57344 },
{ "path": "BlinkREgular.bin", "offset": 65536 }
]
}
]
}
- You can now commit your changes and push to you repo.
NOTE: There is an arguement that it's not good practise to add binaries into source control like this, but it does not seem like its possible to get the binary from the releases section due to CORS, so I think this will be fine.
- Using Chrome or Edge, visit USER_NAME.github.io/REPO_NAME/flash.html
- Plug your board into your computer
- Click the
Installbutton - You should be prompted to select a USB port, pick your device. (This step requires drivers, presumably you already have them if you are here though!)
- It should now start flashing, when its finished you should have a flashed board!