Firmware backup and recovery

If your radio has stopped starting, work down this page from here. The explanations are further down; the steps come first.

The radio will not start after a flash

Start from the least drastic. An ESP32-S3 that cannot run its application still answers a flasher, because the part that talks to the flasher lives in the chip’s own ROM and not in the firmware you just wrote. That is why a failed write is almost always recoverable with the same tool that caused it.

1. Leave it plugged in and switched on, and write again. A half-finished write leaves incomplete firmware, not a broken chip. If the port is still there, this alone fixes most cases.
2. Write a complete image rather than the three files. Use the merged image at 0x0, or the backup you took. A complete image replaces everything a partial write may have corrupted, including the bootloader.
3. If the computer no longer sees a serial port, force the radio into recovery mode by hand — the next section — and then write again.
4. If the port comes and goes, that is a reboot loop, and it is the case recovery mode exists for. Do not keep retrying into it; force recovery mode first.

Do not start a second write on top of a first one that reported success. If the tool says the firmware was written and only the automatic restart failed, the image is already in place — switch the radio off and on by hand instead.

Forcing recovery mode by hand

Look at the board first. Some ATS Mini boards have BOOT and RESET buttons soldered on, some have only BOOT, and some have neither. Which of the sequences below applies to you depends on that.

With both buttons: power the receiver on, connect it over USB, press and hold BOOT, press RESET, release BOOT.

With BOOT only: connect it over USB, press and hold BOOT, power the receiver on, release BOOT.

With no BOOT button: if the pads are there, bridging them briefly does the same job the button would. If there are no pads at all, the firmware project’s own answer is to short the ESP32-S3’s pin 27 (GPIO0) to ground to imitate the press. Either way you are opening the case and touching the board while it is powered, which is not a step to take casually — but it is the documented way in.

In recovery mode the radio does nothing of its own: it is not running its firmware at that point, so a blank or frozen display is not a failure. What matters is the computer — it should show a serial port, and the flasher should connect to it as usual.

What BOOT and RESET actually do

RESET restarts the processor. BOOT, held down at the moment it restarts, tells the processor to start the ROM’s download mode instead of the firmware in flash. Neither button repairs anything. What they give you is a guarantee that the chip is listening to the flasher rather than trying to run a broken image.

That guarantee is the reason a board without those buttons is riskier to flash. Without them you depend on the flashing tool talking the chip into download mode over the USB link itself, which works while the chip is behaving. When it is not — an image that crashes before USB is ready, or a reboot loop that keeps dropping the port — there is no button to fall back on, and you are down to shorting a pin inside the case. It is worth knowing which kind of board you own before you flash it, not while you are trying to rescue it.

Taking a backup before you write

A backup here means a byte-for-byte copy of the radio’s whole 8 MB flash: bootloader, partition table, firmware, and everything the radio has stored in between. It is a complete image, which is what makes it a complete way back.

In the firmware installer it is the first half of step 5, Read a backup of the current firmware first, and it is on by default. Reading all 8 MB takes a few minutes; when it finishes you get a file to download. Save it somewhere you will find it again — the file name carries the date, and a backup you cannot locate is not a backup.

By hand, esptool.py reads the same thing with read_flash 0x0 ALL at --baud 921600. The firmware project documents the exact command.

You can only take a backup while the radio still works. After a bad flash there is nothing left worth copying. This is the one step in the whole process that cannot be done later.

Restoring a backup

A backup is a complete image, so it goes to 0x0, exactly like a merged release image. There is no separate restore procedure and no special tool.

In the installer, tick I have a raw .bin image rather than a release archive in step 4 and load the file. The app reads the image’s own header, recognises a complete image and offers 0x0. It cannot check a bare .bin against your hardware — there is no variant marker in one — so it asks you to confirm you want to write it anyway. Your own backup off this radio is the clearest case there is for saying yes.

By hand, it is write_flash at 0x0 with the backup file, and the firmware project documents that command too.

What a failed write looks like

It looks like a progress bar that stops, and an error. It does not look like an explosion, and the radio does not tell you anything — nothing on the radio knows a write was half-finished. The three outcomes the installer separates are worth knowing apart, because they call for opposite responses:

The write did not finish

The radio may not start until something is flashed successfully, but it is still connected and still listening. Write again, or write your backup. This is the ordinary bad case and it is recoverable.

Written, but the restart failed

The firmware is already in place. Only the automatic reboot failed. Switch the radio off and on by hand. Do not flash it a second time.

The backup failed

Nothing was written at all. The radio is exactly as it was before you started, so there is nothing to recover — just start again.

When it is not the firmware

Several failures that feel like a dead radio are not. Before assuming the worst:

• A charge-only USB cable powers the radio and shows nothing to the computer. It is the most common cause of “the port disappeared”.
• A USB hub between the radio and the computer. Try a port on the machine itself, especially if the connection works at the slow rate but will not speed up for the transfer.
• The wrong port. If a tool reports that the board is not an ESP32-S3, you have picked some other USB serial device — the radio is fine.
• A sleeping or switched-off radio answers nothing. Wake it before you connect.
• The chip answers but its flash memory does not. That one is not a cable problem, and changing cables will not help; it points at the radio’s own board.

When the radio is running again, Installing firmware covers the variants, the addresses and the choice between a three-file and a merged write, and the installer does the identification for you.