Easy Install — Windows, macOS & Linux

One download with guided scripts for every desktop system. Use it when the browser installer is not available, for example in Safari or Firefox.

Download Easy Install (.zip)

ESP32-Tailnet-Gateway-v3.0.2-EASY-INSTALL-Windows-macOS-Linux-WITH-NOTICES.zip · release page · ZIP and source checksums

If no board answers, put it in download mode: hold BOOT, press and release RST, then release BOOT and run the script again.

Before you start

An ESP32-S3 board with 8 MB octal PSRAM and at least 8 MB of flash (N8R8 or N16R8, see Hardware) and a USB data cable.
Unzip the whole package into a folder and open START-HERE.txt.
Close serial monitors and other flashing tools.

Windows

Nothing to install: the package includes esptool.exe (Espressif, GPL-2.0-or-later).

New device: double-click windows\INSTALL-NEW-DEVICE.bat and type ERASE to confirm.
Configured device: double-click windows\UPDATE-KEEP-SETTINGS.bat.

The scripts check the checksums, find the board (or use the port you give, e.g. UPDATE-KEEP-SETTINGS.bat COM5) and refuse anything that is not an ESP32-S3.

macOS and Linux

Requires Python 3 and esptool 5. Once:

python3 -m pip install --user "esptool>=5,<6"

Then, in a terminal inside the package folder:

sh macos-linux/install.sh new        # new device, erases everything
sh macos-linux/install.sh update     # configured device, keeps settings

Add the port if several are found, e.g. sh macos-linux/install.sh update /dev/ttyACM0. On Linux, if access is denied, add your user to the dialout (Debian/Ubuntu) or uucp (Arch) group and log in again.

What the scripts write

Mode	Writes	Settings
New device	Erase, then write bootloader, partition table, initial OTA data and application at the offsets below	Erased
Update	Bootloader `0x0`, partition table `0x8000`, OTA data `0x19000`, application `0x20000`	Kept

The update mode also moves a 2.x gateway to the 3.0 flash layout, keeping its settings. Between 3.x versions the Web UI update (System → Firmware) is preferable: it keeps the previous image as a fallback.

Troubleshooting

No port found: try another cable or USB port; install the CP210x/CH34x driver if your board uses one; then hold BOOT, tap RESET, release BOOT and retry.
"Not an ESP32-S3": this firmware needs an ESP32-S3; other chips are refused before anything is written.
Checksum error: download the package again; never flash files that fail the check.
Interrupted flashing: run the same script again. The board's ROM bootloader cannot be damaged by a failed write.