Firmware Update Platform Support

This page documents how the browser-based firmware flashing flow behaves on each platform.

Support Matrix

Platform	Current Status	Notes
Windows	Supported	Usually exposes serial devices as COMx.
Ubuntu / Linux	Supported	Usually exposes serial devices as /dev/ttyUSB* or /dev/ttyACM*.
macOS	Supported	Common device names are /dev/cu.* or /dev/tty.*.
Android	Partial	Can work when the browser exposes Web Serial and the device supports USB OTG.
iOS / iPadOS	Not supported for direct USB flashing	Web Serial is not available for this flow in iOS browsers.

Windows

Windows is supported when:

• The browser exposes Web Serial
• The USB serial driver is installed correctly
• No other application is already holding the serial port

Common serial naming:

• COM3
• COM5
• COM12

Typical failure cases:

• Another serial monitor already opened the port
• The board disconnected and Windows kept a stale handle
• USB cable or driver issues

Ubuntu / Linux

Ubuntu/Linux is supported when the browser exposes Web Serial and the logged-in user can access the serial device.

Common serial naming:

• /dev/ttyUSB0
• /dev/ttyUSB1
• /dev/ttyACM0

Typical Linux-specific issues:

• The user does not have permission to access the serial device
• Another process is already using the device
• The board appears on a different ttyUSB* or ttyACM* path after reconnect

If access permissions are the problem, check the ownership and group of the serial device and verify the user has access to the appropriate serial-device group such as dialout.

macOS

macOS is supported in the same browser-based flow as Windows and Linux, provided the browser exposes Web Serial.

Common serial naming:

• /dev/cu.usbserial-*
• /dev/cu.SLAB_USBtoUART
• /dev/cu.usbmodem*
• /dev/tty.*

Important clarification:

• macOS is not the same as iOS
• macOS desktop browsers can support direct USB flashing in this implementation
• iPhone and iPad browsers do not use this direct USB serial flow

Android

Android support is more limited than desktop.

Direct USB flashing may work when:

• The browser exposes Web Serial
• The phone supports USB OTG
• A proper USB OTG adapter and data cable are used

This is treated as partial support because browser and hardware combinations vary more widely than on desktop.

iOS / iPadOS

Direct USB flashing is intentionally treated as unsupported in the current implementation.

Reason:

• The current admin firmware update page depends on esptool-js
• esptool-js depends on Web Serial
• The current iOS browser environment does not expose the same Web Serial path used by this page

This is why the UI now blocks the connect flow early on iOS/iPadOS and explains the limitation instead of allowing a generic serial failure.

Why The App Differentiates iOS And macOS

The firmware update page now detects these separately:

• macOS: desktop/laptop environment that may support Web Serial
• iOS / iPadOS: mobile/tablet environment that does not support this direct USB flashing path

This avoids the common confusion that “Apple platform” is a single case. In practice:

• MacBook and iMac users can use the direct browser flasher when browser support exists
• iPhone and iPad users need another firmware distribution channel

Operational Recommendations

Use these defaults for day-to-day firmware flashing:

1. Prefer desktop Chrome, Edge, or Brave on Windows, Ubuntu/Linux, or macOS.
2. Use a direct USB data cable instead of a charge-only cable.
3. Close any serial monitor before connecting.
4. On Ubuntu/Linux, verify serial-device permissions before troubleshooting the browser.
5. Treat iOS/iPadOS as an OTA/BLE/Wi-Fi update target, not a direct USB flasher target.