Documentation¶
How to get your own ESPHome firmware onto a Shelly with ota.py, why the tool does what it does, and what to do when it does
not work. The README has the short version; these pages have the details.
Where to start¶
- New here? Read the Step-by-step guide.
- Find your device on the device pages: the ESPHome config it needs, the exact commands and the log lines to look for.
- Run the three steps
fetch,build,send(Commands). - If something stops or looks wrong, look it up below or in Troubleshooting.
- Before you share a package, read the Credential check: it can contain your Wi-Fi password.
Pages¶
| Page | What is in it |
|---|---|
| Step-by-step guide | The whole way for a user: check, prepare, config, build, send, afterwards, way back |
| Developer guide | Adding devices, testing, reports, profiles, tool changes, release |
| Device pages | One page per device: config, pins, commands, log lines, pitfalls |
| Commands | fetch, build, send, restore, ble, log and the rest, with all options |
| Bootloader and slots | Why ESPHome's bootloader is shipped, min_version, why the app must land in slot 0 |
| Troubleshooting | Header errors, empty log, battery devices, eFuse, power cycle |
| Recovery over UART | Back to Shelly OS with esptool |
| Test on a dev board | A flash image of a package for a board: play the whole update through, for any device |
| Credential check | Secrets inside images and packages |
| Versions | Tool version, build report, profile revisions |
Something went wrong¶
Tip
Always run send with --watch: the log answers most questions.
| What you see | Where to look |
|---|---|
send refuses: update target slot is not 0 |
Troubleshooting, The app must land in slot 0 |
send warns: "this firmware does not reveal the update target slot" |
Troubleshooting |
send cannot reach the device: no Wi-Fi, no access point (Zigbee firmware) |
Troubleshooting, ble |
build stops with "differs from Shelly's in ..." |
Build refuses to replace the bootloader |
| No progress or confirmation from the device log | No progress, no device log |
| H&T Gen3: HTTP 500, "Battery below 30 percent" | Battery devices |
| ESPHome does not start after the update | ESPHome does not start after the update |
| ESPHome OTAs "work", but the version does not change | Troubleshooting, min_version |
build warns about credentials in the image |
Credential check |
| You want Shelly OS back and Shelly firmware still runs | restore |
| You want Shelly OS back and the device runs ESPHome | Recovery over UART |
| A log or package needs to say which tool state made it | Versions |
Outside this folder¶
| Where | What is in it |
|---|---|
devices/ |
The device profiles (one YAML each) and profiles.lock |
partitions/ |
Stock partition tables as ESPHome partitions: CSV, one per profile |
| CHANGELOG | What changed |
| Roadmap | What is planned, and where testers can help |
| Credits | Whose work this tool builds on, and who tested it |
| Contributing | How to help: reports, rules, AI-assisted work, pull requests |