Skip to content

Flash the firmware

There are three ways to get firmware onto the board. If you have no reason to prefer another, use the browser installer.

Method Use it when Needs
A — Browser You just want a working speaker Chrome, Edge or Opera
B — PlatformIO You want to change build settings, or your board has no prebuilt binary Python, a clone of the repo
C — ESP-IDF You already work with ESP-IDF ESP-IDF v5.5.5+

Option A — Install from your browser

Pick your board and click Install. Nothing to download, no toolchain, no command line.

Requirements

Works in Chrome, Edge and Opera on desktop. It uses the Web Serial API, which Safari and Firefox do not implement, and which is unavailable on iOS and Android. Plug the board in over USB before clicking Install.

Each board has an Install button for the latest release and, beside it, a dashed Install beta button for a build of the current staging branch. Read beta builds before using the second one.

Generic boards

  • ESP32-S3 + external DAC

    The standard build, for an ESP32-S3 with a PCM5102A or similar I2S DAC.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • ESP32-S2 + external DAC

    For ESP32-S2 boards with an external I2S DAC.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Waveshare ESP32-S3

    For Waveshare ESP32-S3 boards.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Amplifier boards

  • SqueezeAMP

    ESP32 + TAS5756. Includes Bluetooth A2DP. For 8 MB flash boards.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • SqueezeAMP (4 MB flash)

    For the 4 MB flash variant. No Bluetooth — it does not fit.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • SmartAmp

    ESP32 + Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Esparagus boards

Every Esparagus board is fitted with a TAS58xx amplifier — a TAS5825M or a TAS5805M, detected at startup, so one binary covers both. The Audio Bricks also have W5500 Ethernet. Bluetooth A2DP only exists on the original ESP32.

  • Esparagus Audio Brick

    ESP32 + TAS58xx. Includes Bluetooth A2DP and W5500 Ethernet.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Audio Brick S3

    ESP32-S3 + TAS58xx, with W5500 Ethernet.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Audio Brick Dual

    ESP32-S3 + two amplifiers: stereo plus a bridged mono subwoofer.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Audio Brick Dual + USB audio

    The Dual, also enumerating as a USB speaker. See USB audio.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Louder

    ESP32 + TAS58xx. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Louder S3

    ESP32-S3 + TAS58xx.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

HiFi boards

HiFi-ESP32 and HiFi-Esparagus carry a PCM5100 line-level DAC and no amplifier — they feed an amp or active speakers. The -ESP32 boards have W5500 Ethernet and an OLED; the Esparagus ones do not.

  • HiFi-ESP32

    ESP32 + PCM5100, Ethernet and OLED. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • HiFi-Esparagus

    ESP32 + PCM5100, WiFi only. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • HiFi-ESP32-S3

    ESP32-S3 + PCM5100, Ethernet and OLED.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • HiFi-Esparagus-S3

    ESP32-S3 + PCM5100, WiFi only.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Loud and Echo boards

Loud-ESP32, Loud-Esparagus and Esparagus Echo drive MAX98357A amplifiers directly — connect speakers to the board.

  • Loud-ESP32

    ESP32 + MAX98357A, Ethernet and OLED. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Loud-Esparagus

    ESP32 + dual MAX98357A, WiFi only. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Loud-ESP32-S3

    ESP32-S3 + dual MAX98357A, Ethernet and OLED.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Esparagus Echo

    ESP32-S3 + dual MAX98357A, Ethernet, no display.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Amped boards

Amped-ESP32 and Amped-Esparagus put a PCM5100 DAC in front of a TPA3110/TPA3128 amplifier. Connect speakers to the board.

  • Amped-ESP32

    ESP32 + PCM5100 + TPA31xx, Ethernet and OLED. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Amped-Esparagus

    ESP32 rev M, Ethernet and a rotary encoder. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Amped-ESP32-S3

    ESP32-S3 + PCM5100 + TPA31xx, Ethernet and OLED.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Louder boards

Louder-ESP32 carries a TAS58xx DAC and amplifier. The Plus boards have a TAS5825M, the plain ones a TAS5805M — pick the card that matches the board, the pinouts differ.

  • Louder-ESP32

    ESP32 + TAS5805M, Ethernet and OLED. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Louder-ESP32-Plus

    ESP32 + TAS5825M, Ethernet and OLED. Includes Bluetooth A2DP.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Louder-ESP32-S3

    ESP32-S3 + TAS5805M, Ethernet and OLED.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

  • Louder-ESP32-S3-Plus

    ESP32-S3 + TAS5825M, Ethernet and OLED.

    Your browser cannot flash over USB. Use Chrome, Edge or Opera on desktop. Flashing needs a secure (HTTPS) connection.

Once the install finishes, unplug and re-plug the board. It boots into setup mode — carry on to First boot.

Beta builds

The dashed Install beta buttons flash a build of the tip of the staging branch, rebuilt on every push. That is where fixes land before a release, so a beta is the way to try one — or to confirm a bug you reported is gone.

It is also unreleased code. Betas come off the same CI as a release, but nobody has run them on hardware, so treat a failure to boot as expected rather than surprising and report it. Installing the release build again always recovers the board.

A button only appears when the build behind it exists, so the beta buttons are absent between staging pushes, and a board added since the last release shows its beta button alone until a release carries a build for it.

Prefer to flash manually?

Every build above is also published as a merged .bin, on the releases page for releases and under the beta tag for the current staging build. Merged images are flashed at offset 0x0 with esptool or the esptool-js web tool.

Only the variants listed above are published — anything else in build environments you build yourself.

Option B — PlatformIO

PlatformIO handles the toolchain setup for you.

# 1. Install the PlatformIO CLI
pip install platformio

# 2. Clone the project, including submodules
git clone --recursive https://github.com/rbouteiller/airplay-esp32
cd airplay-esp32

# 3. Plug the board in over USB and flash the firmware
pio run -e esp32s3 -t upload

# 4. Flash the SPIFFS image containing the web UI and data files
pio run -e esp32s3 -t uploadfs

# 5. Optionally watch the serial output
pio run -e esp32s3 -t monitor

Step 4 is not optional

PlatformIO does not write the SPIFFS partition as part of -t upload. If you skip -t uploadfs, the device boots but the captive portal and web UI pages are missing, and you get "file not found" errors during setup. See SPIFFS filesystem.

Replace esp32s3 with whichever environment matches your hardware — see build environments for the full list.

Option C — ESP-IDF

# 1. Install ESP-IDF v5.5.5 or newer:
#    https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/

# 2. Clone the project, including submodules
git clone --recursive https://github.com/rbouteiller/airplay-esp32
cd airplay-esp32

# 3. Activate the ESP-IDF environment
source /path/to/esp-idf/export.sh

# 4. Build and flash, including the SPIFFS "storage" partition from data/
idf.py set-target esp32s3
idf.py build
idf.py -p /dev/ttyUSB0 flash

# 5. Optionally monitor the serial output
idf.py -p /dev/ttyUSB0 monitor

Unlike PlatformIO, idf.py flash writes the SPIFFS partition in the same step, so there is no separate filesystem upload to remember.

Next

Continue to First boot.