ESP-SDR turns the ESP32's built-in 2.4 GHz Wi-Fi radio into a software-defined radio (SDR). It lets you capture the radio signal itself and process it in software, so you can view the spectrum and study signals beyond ordinary Wi-Fi packets. No separate SDR hardware is needed. The ESP32-C5 also supports reception in the 5 GHz band.

With the help of LLMs, we discovered an undocumented debug path that bypasses the chip's fixed-function Wi-Fi modem. This gives software access to raw radio samples, called I/Q samples, from the built-in receiver. ESP-SDR captures short bursts of these samples and sends them to your computer over USB or UART for analysis. It can also compute spectra on-device, including continuous RF capture on selected chips.

The diagram shows the hardware's receive and transmit paths; this firmware currently implements reception only.

Project overview · Browser SDR viewer · Browser firmware installer

Parts of the firmware code are AI-generated. While we have a very good understanding of how the IQ sampling functionality works on the ESP32-C61 chip (used in our ESPARGOS One array), making IQ sampling work on the whole range of ESP32 family chips would have been too much work without LLM support.

The firmware can compute FFTs on the device and send compact spectra instead of raw I/Q. The viewer queries each device's supported rates, FFT sizes and transport before offering this mode.

Continuous capture keeps the RF writer running, but the CPU analyzes only selected FFT windows. It does not deliver every sample or guarantee that every short RF event will be visible. Snapshot FFT stops reception between captures; the viewer labels these gaps explicitly. Raw I/Q capture remains available separately.

The original S3 Turbo Mode was developed by Zoltan Doczi from Z2Labs. The shared implementation extends it with C6/C61 bank rotation, C3 live-bank reads, S31 dual-core SIMD processing with continuous bank rotation, and portable snapshot FFTs. See spectrum protocol and hardware validation for the wire format, limitations and test results. The S3 ring diagnostic host tool is tools/s3_ring.py.

Connect over native USB or a 3.3 V USB-to-UART adapter with crossed TX/RX and common ground, using the pins above. Both interfaces carry the same request/response protocol: send newline-terminated ASCII commands and read text replies. Capture replies also include a binary I/Q payload.

Query INFO and CAPS to identify the firmware and supported features. LIMITS? reports receive-control limits, RANGE? reports the tuning range, and TRANSPORT? identifies the active interface. Configure reception with FREQ <MHz>, BANDWIDTH <MHz> and GAIN commands.

Request a snapshot with CAP16 <samples> <rate-index> for signed 8-bit I/Q or CAP20 <samples> <rate-index> for packed signed 10-bit I/Q. The reply is DATA <samples> <crc32-hex> <capture-microseconds>, followed by exactly ceil(samples × bits-per-component × 2 / 8) binary bytes. Verify the payload CRC32 before using the samples. Rate indices 0–6 select 80, 40, 20, 10, 8, 4 or 16 MS/s respectively; use only rates advertised by LIMITS?.

Finish reading each reply before sending another command. Failures return ERR <reason>. SYNC <nonce> echoes the nonce to let clients resynchronize after an incomplete transfer. One client controls the radio at a time; RELEASE or five seconds of idle time releases it, while other clients receive ERR busy.

firmware-targets.json lists the supported profiles and pins their ESP-IDF commits, including the preview SDK for S31. Check out the matching SDK, initialize its submodules, run install.sh <target>, and source export.sh.

Use a separate build directory and configuration for each chip:

idf.py -B build-s3 -DIDF_TARGET=esp32s3 \
  -DSDKCONFIG=sdkconfig.s3 \
  -DSDKCONFIG_DEFAULTS=sdkconfig.defaults.esp32s3 build
idf.py -B build-s3 -p /dev/ttyACM0 flash

Substitute the target and paths for your chip. S31 also requires idf.py --preview.

• main/targets/<target>/: chip receiver or adapter, tuning helpers, and the linker guard for its capture SRAM. CMake selects only the requested target.
• main/families/c5_c6_c61/: receiver shared by C5, C6, and C61; its chip.h comes from the selected target directory.
• main/common/: burst serial transport, gain control, limits, and bandwidth helpers. The gain-table wrapper is linked only for C61 and S31.
• main/diagnostics/: optional register probes, excluded from release exports.
• platform/esp32s2/: pinned ROM USB CDC compatibility component.

The application component and UART configuration stay in main/. Target SDK defaults stay at the repository root for the build tools and ESP-IDF defaults lookup. The firmware uses the burst protocol over UART/native USB; the former Ethernet and vendor USB streaming application is no longer included.

Run python3 -m unittest discover -s tests for host checks. Build every profile with tools/build_firmware.py and its pinned SDK before distributing a change; the CI matrix does this automatically. Preserve the target SRAM guards and gain-table linker wrappers when moving or refactoring receiver code.

Hardware AGC is the default. GAIN MANUAL <index> sets manual gain; GAIN HARDWARE restores AGC. LIMITS? reports available gain indices, bandwidths, sample rates and bit depths. BANDWIDTH <MHz> sets approximate analog bandwidth; zero selects the widest setting.

All eight chips accept tuning attempts from 100–6000 MHz in 1 MHz steps. The viewer shows an informational warning outside 2400–2483.5 MHz, with 5150–5895 MHz also treated as the supported 5 GHz Wi-Fi band on C5. The warning never blocks tuning. These are software attempt limits; the expanded range has not been hardware validated.

• ESP32: 80/40/16 MS/s.
• C3: 80 MS/s; 14–62 MHz analog bandwidth.
• C5: 11–48 MHz bandwidth; selects its 5 GHz RF path above 3000 MHz.
• C61: 80/40/20/10/8/4 MS/s; 13–54 MHz bandwidth.
• C6: 80 MS/s; 12–54 MHz bandwidth.
• S2: 80/40/16 MS/s; 15–60 MHz bandwidth; up to 12,284 complex samples.
• S3: 13–69 MHz bandwidth.
• S31: 80/40/20/10/8/4 MS/s; 13–54 MHz bandwidth.

Captures have gaps; nominal sample rates exceed sustained serial throughput. Gain and power are uncalibrated. Extended tuning does not guarantee PLL lock or reception; the viewer uses the ISM-band warning described above.

See receive-control details.

Florian Euchner

Zoltan Doczi

ESP-SDR is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (GPL-3.0-or-later). See LICENSE for the full terms. It is provided without any warranty, including implied warranties of merchantability or fitness for a particular purpose.

We chose the GPL because we want improvements to ESP-SDR to make their way back to the community. When you distribute modified versions, the GPL requires you to make the corresponding source available to recipients under the GPL, so they can study, share, and build on those improvements. We encourage you to contribute changes upstream, but the GPL does not require upstream submissions or publication of private modifications. See the GNU GPL FAQ.

The discovery of the capture mechanism itself is not protected by copyright: copyright covers the code and other copyrightable expression, not the underlying facts, ideas, or methods. You are free to independently implement the mechanism in your own projects under a license of your choice.

Third-party components retain their own licenses and copyright notices, including the Apache-2.0 ESP-IDF compatibility code in platform/esp32s2/esp_usb_cdc_rom_console/, the pinned ESP-DSP component, and the derived FFT kernels in main/targets/esp32s3/s3_fft_rnd.S and main/targets/esp32s31/s31_fft_rnd.S.