Skip to main content

Firmware Update Overview

The admin firmware update page provides browser-based flashing for supported ESP devices using esptool-js and the Web Serial API.

Public Firmware Update Page​

Use the public firmware update page here:

This route is intended for direct access without requiring the admin dashboard flow.

What The Page Does​

The frontend page at /firmware-update allows users to flash firmware to an ESP device over USB using a browser-based flow. The main steps are:

  1. Connect to a supported serial device from the browser.
  2. Detect the ESP chip and basic device information.
  3. Upload a .bin firmware file.
  4. Flash the selected image to the target address.
  5. Reset the device after flashing completes.

This flow is intended for direct USB flashing from a browser and is separate from OTA or backend-managed firmware rollout.

How It Works​

The current implementation relies on:

  • esptool-js for ESP flashing in the browser
  • Web Serial (navigator.serial) for serial transport
  • A browser permission prompt so the user can choose a serial device

Because the page uses Web Serial, platform and browser support matters. The implementation now detects support up front and shows a platform-specific status card before a user starts flashing.

Supported Device Discovery​

The firmware update page no longer assumes only one USB vendor/product pair. It now allows selection of several common USB serial bridges used by ESP boards, including:

  • Espressif native USB serial / USB JTAG serial
  • Silicon Labs CP210x
  • QinHeng / WCH CH34x
  • FTDI
  • Prolific
  • Adafruit-branded serial bridges

This makes the page more practical across Windows, Ubuntu/Linux, and macOS where boards may appear through different USB serial chipsets.

What Changed In The UI​

The page now includes:

  • A platform support card that explains whether the current browser can use direct USB flashing
  • More explicit console hints for serial open failures
  • Platform-aware wording for serial port naming
  • Early blocking for unsupported environments such as iOS/iPadOS

Important Limitation​

This page supports direct USB flashing only when the browser exposes Web Serial. It does not automatically provide firmware update support on platforms that do not expose Web Serial.

If a team needs firmware update from iPhone or iPad, that requires a different update channel such as:

  • OTA over Wi-Fi
  • BLE-based update flow
  • A device-managed download/install flow from backend storage

For the current implementation, prefer a Chromium-based browser with Web Serial support:

  • Google Chrome
  • Microsoft Edge
  • Brave

The page should be served over HTTPS or localhost when testing Web Serial behavior.