Build environments¶

Every PlatformIO environment defined in platformio.ini. The default is esp32s3.

Generic boards¶

Amplifier boards¶

Every Esparagus board is fitted with a TAS58xx amplifier, either a TAS5825M or a TAS5805M. The driver reads the die ID at startup and configures whichever it finds, so the environment does not have to know which part is on the board.

The dual-DAC environments drive an Audio Brick Dual with two amplifiers: stereo at I2C address 0x4C and a second at 0x4D, wired either as a bridged (PBTL) mono output or as a second stereo pair. -dual-uac adds USB audio to the same board.

Sonocotta audio dock boards¶

The HiFi, Loud, Amped and Louder families all come in an -esp32 form with an Ethernet jack and an OLED header, and an -esparagus form without either. Bluetooth Classic exists only on the original ESP32, so no S3 environment has a -bt variant.

Targets without a PlatformIO environment¶

These have sdkconfig defaults and are built through ESP-IDF directly.

idf.py set-target esp32s2
idf.py -DSDKCONFIG_DEFAULTS="config/sdkconfig.defaults;config/sdkconfig.defaults.esp32s2" build

Which builds get a prebuilt binary¶

CI builds a subset of environments and attaches them to each release. These are the ones available in the browser installer:

esp32s3, waveshare-esp32s3, esp32s2, squeezeamp-bt, squeezeamp-4m, smartamp, esparagus-audio-brick-bt, esparagus-audio-brick-s3, esparagus-audio-brick-dual-dac, esparagus-audio-brick-dual-uac, esparagus-louder-bt, esparagus-louder-s3, esparagus-echo, hifi-esp32-bt, hifi-esparagus-bt, hifi-esp32-s3, hifi-esparagus-s3, loud-esp32-bt, loud-esparagus-bt, loud-esp32-s3, amped-esp32-bt, amped-esparagus-bt, amped-esp32-s3, louder-esp32-bt, louder-esp32-plus-bt, louder-esp32-s3, louder-esp32-s3-plus.

The list lives in .github/workflows/targets.json, and each entry needs a matching docs/firmware/<name>.json manifest for the installer to offer it.

Everything else you build yourself. On an ESP32 board that can do Bluetooth the published binary always includes it, so there is no prebuilt squeezeamp, esparagus-audio-brick, esparagus-louder, hifi-esp32, loud-esp32, amped-esp32 or louder-esp32 — build one of those yourself if you want the RAM and flash back.

The same list runs on every push to staging and publishes a rolling beta pre-release, so each of these boards has an untested build of the current development tip available too. A pull request builds only the entries flagged "core": true, which cover every chip and every board support directory without a job per variant, and the matrix does not fail fast, so one board failing to compile no longer stops the others being published.

How sdkconfig layering works¶

All board configuration lives in config/. The generated sdkconfig stays at the project root — that one is a build artifact and is gitignored.

Environments compose their configuration by chaining sdkconfig files left to right, with later files overriding earlier ones:

board_build.cmake_extra_args =
    "-DSDKCONFIG_DEFAULTS=config/sdkconfig.defaults;config/sdkconfig.defaults.squeezeamp;config/sdkconfig.defaults.bt"

Here the common defaults come first, then the SqueezeAMP board configuration, then the Bluetooth overlay. Adding config/sdkconfig.defaults.bt to the end of any ESP32 board's chain is how Bluetooth gets enabled.

Common commands¶

pio run -e <env> -t build      # Build
pio run -e <env> -t upload     # Build and flash over USB
pio run -e <env> -t uploadfs   # Flash the SPIFFS image from data/
pio run -e <env> -t monitor    # Serial monitor at 115200 baud
pio run -e <env> -t menuconfig # Kconfig configuration

To define your own environment without touching platformio.ini, see custom board configuration.