Build & flash guide

Most people just want to flash a pre-built release — head to the flash page for that. This page is for building the firmware yourself.

Hardware

Board	Waveshare ESP32-C5-Touch-LCD-3.5 (ESP32-C5-WROOM-1U)
Flash	32 MB
PSRAM	8 MB (quad SPI)
Display	3.5" ST7796 LCD, capacitive touch
Radio	ESP-SDR — raw I/Q receiver on the ESP32-C5's own Wi-Fi PHY

Get the source

git clone --recurse-submodules https://git.hazaar.dev/jamie/pitscan.git
cd pitscan

The third_party/esp-sdr submodule (GPL-3.0) provides the radio driver and its fixed-point FFT; it's pulled in with --recurse-submodules.

Option A — PlatformIO

The quickest path if you just want a working build:

pio run -e pitscan          # real ESP-SDR hardware build
pio run -e pitscan-sim       # simulated-RF build (no radio, for UI work)
pio run -e pitscan -t upload # flash over USB

PlatformIO uses its own bundled ESP-IDF toolchain. It's the easiest way to build, but the project's "real" build — the one releases are cut from — uses the pinned ESP-IDF checkout below.

Option B — idf.py (pinned ESP-IDF)

ESP-SDR needs private PHY symbols that only exist in a specific ESP-IDF commit, so the authoritative build uses a pinned checkout rather than a stock ESP-IDF release:

. ~/esp/esp-idf-pitscan/export.sh
idf.py set-target esp32c5
idf.py build
idf.py -p /dev/ttyACM0 flash monitor

Simulated-RF build

For UI work away from the radio, build with the simulated field overlay instead of the real receiver:

idf.py -B build-sim -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.sim" build

Desktop preview

There's also a plain-CMake, SDL-based desktop preview of the LVGL UI in host/, independent of both build systems above — handy for UI iteration without any hardware at all.

cmake -S host -B host/build
cmake --build host/build
./host/build/pitscan_preview

Releases

Tagged pushes to the firmware repository build and publish a release automatically via Forgejo Actions. The flash page installs the latest release straight from your browser — no toolchain required.