Flash the ESP32-S3 firmware

Flash the board while it is connected to your Mac. Use a USB data cable; a charge-only cable can supply power without exposing a serial device.

Install the toolchain

Install arduino-cli and configure Espressif’s board package index. The project specifies the ESP32 3.3.x core; do not silently replace it with another major release.

arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:[email protected]
arduino-cli lib install "[email protected]"

If that package-index URL is already configured, you do not need to add it a second time. Version 3.3.12 matches the reviewed upstream CI configuration; follow changes in the project README when updating your checkout.

Build and write

From the cloned project’s root, run:

hardware/flash.sh

The script compiles the firmware, looks for a serial port, switches an already-running bridge into its bootloader, and uploads the result. Wait for a successful upload before disconnecting the board.

The default build targets 8 MB flash, OPI PSRAM, and native USB. Check hardware compatibility if you are using a different board.

Select a port explicitly

List connected boards and pass the actual port from your machine:

arduino-cli board list
hardware/flash.sh /dev/cu.usbmodemYOUR_PORT

YOUR_PORT is a placeholder, not a literal device name. If no device appears, reconnect the cable, check whether it carries data, and consult the board vendor’s bootloader instructions.

Why the script is required

flash.sh force-includes hardware/hid_bridge/nimble_cfg.h in the build. Those BLE buffer settings are needed for the video transport. Compiling the sketch with otherwise similar Arduino defaults can leave the board running with unsuitable buffers.

Keep your source path free of spaces: the script checks this because of the forced-include compiler flag.

Optional diagnostics

hardware/flash.sh --build-only
hardware/flash.sh --debug

--build-only compiles without uploading. --debug includes USB-serial diagnostics. These are diagnostic options, not extra steps required for ordinary setup.

Verify the next connection

Move the flashed board to the iPhone and open ESP32 Agent. A successful firmware upload does not prove Bluetooth pairing or screen mirroring works. Verify those separately in Connect the board and screen.