ESPARGOS - ESP-SDR: Raw IQ Capture with Espressif's ESP32 Chips
ESPARGOS home

ESP-SDR

Raw IQ Capture with Espressif's ESP32 Chips

Espressif Systems' ESP32 microcontrollers are well known for their Wi-Fi and Bluetooth capabilities. We have found an undocumented feature in the chip that allows the firmware to bypass these fixed-function modems to capture raw IQ baseband samples. While others have previously connected an external RTL-SDR or SubGHz transceiver to an ESP32 or used external audio ADCs to capture IQ samples, we actually tap into the chips internal modem ADC signal chain, no extra hardware is required. This opens up the possibility of using the ESP32 as a low-cost software-defined radio (SDR) platform, capable of receiving arbitrary signals in the 2.4 GHz band (and the 5 GHz band on the ESP32-C5).

ESP32 signal chain: RF front-end, ADC/DAC, fixed Wi-Fi modem, and CPU. A green debug path connects the ADC/DAC directly to the CPU for raw IQ reception and transmission, bypassing the Wi-Fi modem.
The raw IQ path bypasses the fixed-function Wi-Fi modem, giving software access to baseband samples.

Try it out in your browser

The best part: You can try this out in your web browser with almost any ESP32 development board! Our web interface shows the power spectrum and waterfall diagram of the captured IQ samples (at a very low duty cycle).

1 Flash ESP-SDR firmware to your board

Connect your board over USB (if available, the native / debug port of your board) and install the SDR firmware using the flasher. Supported chips are the original ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-S2, ESP32-S3 and ESP32-S31.

Open firmware flasher

2 Explore the live radio spectrum

After flashing, unplug the board for five seconds and reconnect. Open ESP-WebSDR and select your device to see the live spectrum.

ESP-WebSDR
ESP-WebSDR in action with an ESP32-S3. Try it yourself in your browser with a supported ESP32 board.

How it works

We assume that Espressif engineers left the IQ sampling path in place for testing and debugging the modem, for example for on-wafer testing in the fab. The exact capture mechanism, trigger modes and memory allocation differ between chips, but the general idea is the same: special debug registers configure the modem's sample-dump engine to write raw IQ samples directly into the chip's internal SRAM, bypassing normal Wi-Fi processing. The firmware reserves SRAM so that the heap cannot use it, then lets the modem write raw IQ into that memory.

For example, on the ESP32-C61, the capture mechanism works as follows: The SRAM inside the ESP32 is organized into banks. Our firmware uses two of these banks and organizes them as a ring buffer. One of the banks is temporarily owned by the modem, which writes raw IQ samples into it, while the other bank is owned by the CPU, which copies the completed samples to a buffer for transfer to the host. The firmware tracks the hardware write pointer to detect when the modem moves to the next bank.

ESP32-C61 two-bank ring: the modem writes bank 3 while the CPU copies samples from completed bank 2. Each bank holds 64 KiB. The writer alternates between banks; the CPU must return a bank before it is reused.
Capture using a ring buffer with two SRAM banks, shown while bank 3 is being filled. The banks exchange roles on the next pass.

IQ sample format

The exact format of the IQ samples is configurable. In our implementation, each complex sample occupies one 32-bit word in memory. Bits 19–10 hold I and bits 9–0 hold Q, both signed 10-bit integers (−512 to +511). Bits 27–20 report the receiver gain setting (an index into the gain table), while bits 31–28 are most likely the internal state of the automatic gain control's finite state machine.

32-bit IQ dump word, most significant bit first: bits 31 to 28 inferred AGC state, bits 27 to 20 RX gain, bits 19 to 10 signed I, and bits 9 to 0 signed Q.
Raw ADC dump word as provided by the modem.

Capture settings

Tuning

2.2–2.7 GHz
4.8–6.0 GHz

5 GHz is only available on ESP32-C5. Exact PLL stability limits differ by chip.

Sample rate

Up to 80 MSa/s

Raw complex IQ capture into memory, with transfer to the host at a low duty cycle.

Bandwidth

~13–54 MHz

Analog RX bandwidth. Exact limits depend on the chip and filter settings.

Gain control

Automatic or manual

Internal hardware AGC or a manually selected fixed receiver gain.

With ESP-SDR, the ESP32 can even capture IQ data beyond the officially supported tuning range. For example, the ESP32-C61 can capture signals up to 2.7 GHz, which includes some LTE and 5G NR cellular bands, such as LTE band 7 and 5G NR band n7 around 2.6 GHz.

How we discovered this

Our starting point was the adctrig function in Espressif's librftest library. With the help of LLMs, we reverse engineered this function to understand how it configures the hardware to capture raw IQ samples. These findings formed the basis of ESP-SDR's capture implementation.

What this means for ESPARGOS

Without any hardware modifications, ESPARGOS One can now phase-coherently capture raw IQ samples. If you already have an ESPARGOS One, update its firmware to the latest version from the dev branch to enable this capability. The hardware already supports it. We currently provide the "IQ Signal Analyzer" demo application, but are working on additional demo applications, including an adapted real-time augmented reality demo for arbitrary signals.

ESPARGOS One antenna array
Phase-coherent ISM-band IQ capture across eight ESPARGOS antennas (real-time screen capture, signal trigger).

The IQ sampling implementation on ESPARGOS One is even more powerful than the browser-based demo (ESP-WebSDR):

  • Higher throughput / duty cycle: ESPARGOS One uses an internal SPI transport interface, which is much faster than the UART interface used by ESP-WebSDR.
  • Signal trigger: Instead of streaming all samples (mostly silence), ESPARGOS One can be configured to stream samples only when a signal is detected.

In addition to the existing Wi-Fi channel state information (CSI)-based demos, ESPARGOS One can now also be used as a low-cost, eight-channel SDR platform for the 2.4 GHz ISM band, operating at a low duty cycle. The benefits of raw IQ capture over processed CSI include:

  • Localize arbitrary signals: ESPARGOS One can now be used to localize arbitrary signals in the 2.4 GHz ISM band, not just Wi-Fi signals. This includes Bluetooth and Bluetooth Low Energy, Zigbee, and Wi-Fi formats that were previously unsupported for CSI capture (e.g., 802.11b and Wi-Fi signals with multiple spatial streams).
  • Array gain: Signal processing and decoding can be performed centrally, improving weak-signal performance.
  • Special waveforms: ESPARGOS One can now be used with waveforms more suitable for specific applications, e.g., pulse compression radar. Even better, some preprocessing for such special applications can happen on the chip itself, so they are not throughput-constrained.
Documentation in progress: The additional capabilities enabled by raw IQ sampling are not yet fully covered in the ESPARGOS library documentation, demos, manual or datasheet.

Limitations

At 80 MSa/s and 32 bits per sample, the modem writes 2,560 Mbit/s into SRAM. Getting those samples off the chip is the bottleneck: the output links are much slower.

A 2560 Mbit/s input pipe connects the modem to SRAM. Output pipes show UART at 3 Mbit/s, SPI at approximately 13.3 Mbit/s, and ESP32-S31 high-speed USB at 480 Mbit/s and Gigabit Ethernet at 1000 Mbit/s. Widths use a square-root scale.
Limited throughput: while the modem can capture 80 MSa/s, the bottleneck is getting the samples off the chip.

The serial burst-capture profiles transfer IQ samples at a low duty cycle, which is enough to display a live spectrum and waterfall in the browser. Packets that arrive between capture windows may be missed. The ESP32-S31 streaming profile offers continuous IQ reception over high-speed USB or Gigabit Ethernet, as described below.

SoapyESPSDR: GNU Radio & Gqrx

High-speed USB

Up to 20 MSa/s

Continuous IQ reception through the native USB port.

Gigabit Ethernet

Up to 40 MSa/s

Continuous IQ reception over a gigabit network.

SoapyESPSDR is our open-source, receive-only SoapySDR driver for the ESP32-S31. It brings continuous IQ samples to desktop applications: listen to signals in Gqrx, record samples, or build your own demodulator in GNU Radio.

Experimental: The firmware and driver are available now. Signal quality may not yet be optimal.

1 Flash the streaming firmware

Connect an ESP32-S31 Function-CoreBoard through its USB debug port or UART adapter. In the web flasher, select the ESP32-S31 Function-CoreBoard · Ethernet / USB for SoapyESPSDR profile and install the firmware.

Open firmware flasher

2 Connect your SDR application

Install SoapyESPSDR on your Linux computer, then connect the board through its native high-speed USB port or Ethernet. Follow the setup guide to select the receiver in Gqrx, GNU Radio, or another SoapySDR-compatible application.

Install and set up SoapyESPSDR
Gqrx displaying the spectrum and waterfall of an LTE signal at 2.63 GHz, continuously sampled at 40 MSa/s by an ESP32-S31 over Ethernet using SoapyESPSDR.
LTE at 2.63 GHz, continuously sampled at 40 MSa/s over Ethernet with an ESP32-S31 and SoapyESPSDR, displayed in Gqrx. Click to view at full size.

More information and firmware

  • ESP-SDR firmware: firmware source code and build instructions.
  • SoapyESPSDR driver: installation and setup for desktop SDR applications.
  • ESP-WebSDR browser interface: browser-based spectrum viewer and firmware flasher.
  • The firmware of ESPARGOS One remains closed source for now, but we are considering on open-sourcing it now that this "secret" IQ functionality that we were keeping private has been revealed.

FAQs

Yes, this is also possible. On ESPARGOS One, even phase-coherent transmission is possible. However, we are not providing a transmitter implementation at this time due to the potential for misuse.

No, this is a feature of the ESP32's modem that was not documented in the public datasheet. As far as we are concerned, it is not a security vulnerability, but rather an undocumented capability that can be used for SDR applications. That being said, many ESP32-powered devices are connected to various cloud services which allow the manufacturer of to update the firmware remotely. If sensitive data is transmitted without encryption in the ISM bands, this could pose a security concern. In that case, the underlying issue is the unencrypted transmission. The ability of the ESP32 to transmit arbitrary signals, on the other hand, could be abused for jamming or other malicious purposes, which is why we are not providing a transmitter implementation at this time.

Yes: on the ESP32-S31, SoapyESPSDR connects GNU Radio, Gqrx and other SoapySDR-compatible applications to continuous IQ reception at up to 20 MSa/s over high-speed USB or 40 MSa/s over Gigabit Ethernet. Other supported ESP32 models use the browser viewer with the standard burst/FFT firmware profiles.

ESP-SDR currently supports the original ESP32, ESP32-C2 (26 MHz crystal), ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-S2, ESP32-S3 and ESP32-S31. We are working to extend the range of supported ESP32 chips. Support for additional models will most likely be possible, but each chip needs its own implementation.

Yes, this is possible. An external mixer can translate signals from other frequency bands into the ESP32's transmit / receive range. We already have multi-channel prototype hardware for this.

Acknowledgements

User h0m3us3r first disclosed this capability for the ESP32-S3 on Reddit, including firmware source code, a few days before our announcement. They achieve 80 MSa/s of sustained throughput using an additional FPGA to handle the transfer. Since we have been independently working on IQ capture for several months now, we also wanted to share our findings with the community.