Phase 2 - Flasher Web

Goal: flash an ESP32 from a browser using Web Serial and a firmware .bin uploaded through the Phase 1 controller.

Implemented scope:

/flasher page.
Firmware catalog loaded from GET /api/v1/firmware.
Firmware cards display name, version, application, compatible hardware, size, and SHA-256.
Firmware selection.
Firmware download from GET /api/v1/firmware/{id}/download.
Web Serial connection flow.
ESP32 flashing flow through Espressif esptool-js.
Progress bar and status messages.
User-readable errors for unsupported browser/context, denied access, missing port, disconnection, download failure, and write failure.

Out of scope for Phase 2:

OTA.
Provisioning.
Fleet Management.
Edge OS.
Firmware generation.

Secure Context

Web Serial requires a secure browser context. Accessing the VM directly through plain HTTP by IP address is not enough for real Web Serial use:

http://192.168.1.62:88/flasher

Observed behavior on that URL:

/flasher loads.
Firmware catalog loads.
Web Serial is blocked by browser context.
The page displays a warning.

Minimal approved test path for Phase 2 is a local SSH tunnel from the Mac:

ssh -N -L 18888:127.0.0.1:88 codex@192.168.1.62

Then open:

http://localhost:18888/flasher

Observed behavior through localhost tunnel:

/flasher loads.
No secure-context warning is shown.
The Connect ESP32 button is enabled.

For real use through iot.aeizoon.com, HTTPS must be configured.

Flash Address

The current firmware catalog does not yet store a flash address. The Flasher page therefore provides an operational Flash address field with default value:

0x0

If a provided .bin requires a different address, set it manually before flashing.

HTTPS Validation Route

As of 2026-07-06, HTTPS access is configured through NPM.

Operational URLs:

https://iot.aeizoon.com/
https://iot.aeizoon.com/flasher
http://192.168.1.62:88/   # internal access only

Physical Phase 2 validation must be performed from:

https://iot.aeizoon.com/flasher

Do not use the localhost tunnel except for punctual diagnostics.

Browser pre-check performed:

https://iot.aeizoon.com/flasher loads.
Page protocol is https:.
The insecure-context warning is not shown.
The Connect ESP32 button is enabled by the page.
Firmware catalog currently loads with 0 items until a real .bin is uploaded.

Physical Validation Adjustment

After testing an ESP32 Ethernet/WiFi AliExpress board through an external USB-TTL adapter, the default baudrate was changed to 115200 because this board was stable at 115200 and unstable at 921600.

The Flasher also now resolves Auto-detected flash size before calling writeFlash() instead of passing detect directly to esptool-js.

Cache and Fit-Check Adjustment - 2026-07-06

A repeated physical test still showed File 1 doesn't fit in the available flash, and the browser log did not include the latest diagnostic messages. This indicated that the HTTPS path was serving an older cached Flasher script.

Applied correction:

/flasher now references /js/flasher.js?v=phase2-20260706-3.
/flasher now references /css/app.css?v=phase2-20260706-3.
flasher.js logs Flasher build: phase2-20260706-3 on load.
Static resources served by the Spring backend are configured with no-cache headers.
Because NPM may still add external cache headers, asset version query strings must be bumped after Flasher JS/CSS changes.
Flash size now defaults to Keep firmware setting, avoiding the esptool-js fit check that can reject a valid image before writing.
Auto-detected size check remains available for diagnostics.

Next validation should use:

URL: https://iot.aeizoon.com/flasher
Baudrate: 115200
Flash size: Keep firmware setting
Confirm first log line: Flasher build: phase2-20260706-3