Browser Flasher

Browser Flasher

The TankSync browser flasher lets you write firmware to a board over WebSerial — no esptool, no Python, no IDF toolchain. Plug the board into USB, pick the target, click Install.

Live at: tanksync.smartghar.org/firmware

Works in Chrome / Edge on desktop (Windows / macOS / Linux). Firefox + Safari don't support WebSerial. Mobile browsers won't work either — flashing needs a real USB port.

---

What you'll see — step 1: pick a board

Open the flasher page and pick which board you're flashing. There are two cards:

• Receiver Hub (RX) — flashes the latest rx-vX.Y.Z binary for the ESP32 DevKit hub
• Transmitter (TX) — flashes the latest tx-vX.Y.Z binary for the ESP32-C3 SuperMini

Both cards show the current published version (matches what's on the Releases page at this exact moment).

---

Step 2: connect

Click Install on the matching card. The browser opens a system port-picker dialog:

Pick the CP210x entry (or USB JTAG/serial debug unit on ESP32-C3). On a fresh machine you may have to install the SiLabs CP210x driver first:

OS	Driver
Windows	Silicon Labs CP210x VCP driver
macOS	Usually auto-installed since Big Sur. Otherwise grab the same driver from Silicon Labs.
Linux	Built into the kernel; no driver needed. Make sure your user is in the dialout group.

---

Step 3: wait

The flasher progresses through:

1. Connect — handshakes with the bootloader. ~3 s.
2. Erase — wipes the flash partitions that will be overwritten. ~5 s.
3. Write — pushes the binary. ~45 s for hub firmware, ~25 s for TX.
4. Verify — reads back a checksum. ~5 s.

Total: under a minute in steady-state. The button on the card turns green when done. Unplug the board, plug it into its real power source, and continue with First Boot.

---

Troubleshooting

"Failed to open serial port"

• Make sure the device is plugged in. Re-plug if it isn't appearing in the picker.
• Close other apps that might be holding the port — Arduino IDE, idf.py monitor, PlatformIO, Tio.
• Linux: confirm ls /dev/ttyUSB* (or /dev/ttyACM* for the C3) shows the device. If it doesn't, the CP210x driver / native USB-JTAG is missing.

"Install undefined" / button does nothing

Refresh the page. The browser flasher's Turnstile token expires after ~5 minutes of idle. A fresh page-load mints a new token.

"Chip not detected" / connect fails

• The board is in normal run mode instead of download mode. Hold BOOT, tap RESET, release BOOT to force the bootloader, then retry.
• USB cable is power-only (no data lines). Try a different cable — the kind that came with a phone is usually OK.

Verify-step mismatch

Almost always a flaky USB cable or hub. Try a different cable, or plug directly into the laptop instead of through a USB hub.

I want to flash a different version (older / pre-release)

Click the gear icon next to the board card and pick a specific tag. The flasher reads the GitHub Releases list directly — anything you've ever published is selectable.

For absolute control (your own custom .bin file), use the Manual .bin upload flow from the hub's local web UI (System → Firmware → Manual upload) — that path bypasses the flasher entirely.

---

Why this is safer than esptool for most users

• No flash-offset mistakes. Browser knows where the partition table goes, where the app binary goes, no 0x10000 magic numbers to memorize.
• Erase is scoped. Wipes only the OTA partition + app — your NVS-stored Wi-Fi credentials, paired transmitters, and calibration survive the update. (esptool ... erase_flash would wipe everything.)
• Version is authoritative. The flasher pulls from the published Releases page; what you flash is exactly what other users are running.

For development (custom builds, debugging from idf.py monitor), use the IDF toolchain — see Manual Flashing.

---

How the page works (technical)

The flasher uses the esp-web-tools <esp-web-install-button> custom element, wrapped in a TankSync-branded card with a progress stepper. Behind the scenes:

• GET /api/firmware/web-releases — returns the latest published tag per binary (uses GitHub Releases as the source of truth).
• GET /api/firmware/esp-web-manifest?target=<rx|tx>&tag=<rx-v2.8.5> — returns the manifest.json esp-web-tools needs, pointing at the binary asset on the Releases page.
• A Turnstile token gates the manifest endpoint (abuse protection — flashing's free, scraping is rate-limited).

The whole flasher is part of the proprietary cloud server. The firmware it flashes is open-source — anyone can run their own flasher or use esptool against the published .bin files.