ESP-SDR on Zephyr

A software defined radio on the ESP32-S3 Wi-Fi radio for Zephyr: I/Q capture from the receiver, I/Q playback through the transmit DAC. Ported from ESPARGOS esp-sdr and extended; a west manifest repository and Zephyr module laid out like example-application.

Warning

This project is neither intended nor qualified for productive use!

The main purpose of this project is "Spaß am Gerät"

• This project views safe operating parameters as suggestions
  • Radios may be driven beyond their design specifications
  • Generated signals may not be compliant with your local regulations
• Be a good neighbor in the spectrum
  • Don't perform radiative tests
  • For development you can connect two devices throug coxial cable with a 30 to 60 dB attenuator
• The firmware may permanently alter the radios' analog characteristics
  • Devices that ran any firmware from this project should be regarded as tainted
  • This disqualifies the device from any future use in certified products
  • It is recommended to mark any used devices in a visible way

Contents

Path	What
lib/	esp_sdr: the library (CONFIG_ESP_SDR) ieee802154: software O-QPSK PHY and Zephyr radio driver (doc/ieee802154.md)
include/	esp_sdr/: the API, esp_sdr.h, esp_sdr_rx.h, esp_sdr_tx.h, esp_sdr_ring.h, esp_sdr_paced.h, esp_sdr_diag.h, esp_sdr_replay.h, ieee154_phy.h, ieee154_esp_sdr.h
apps/	capture: capture survey on the console stream: VITA 49.2 RX and TX over USB (CDC-NCM) osmosdr: HackRF-style USB SDR for GNU Radio and gqrx osmosdr_serial: the same over USB-Serial-JTAG (C6, C5) link: QAM or OFDM packet link wpan: 802.15.4 test shell rfprobe: bench probe (tuning, tones, registers) multiapp: one firmware that runs the others (doc/multiapp.md) common: USB with DFU, watchdogs, crash records
tests/	unit (host), integration (one board), regression (two boards); see doc/testing.md
doc/	Guides, register pages, the Doxygen and Sphinx build
scripts/	west dfu (west_commands/), test runners
boards/	waveshare/esp32c5_zero: Waveshare ESP32-C5-Zero
zephyr/	module.yml and the librftest.a blobs
west.yml	The workspace pins (see Dependencies)

Getting started

west init -m https://github.com/cyber-murmel/esp-sdr-zephyr esp-sdr-ws
cd esp-sdr-ws
west update
west blobs fetch hal_espressif
west blobs fetch esp-sdr-zephyr
west build --pristine --sysbuild --board xiao_esp32s3/esp32s3/procpu esp-sdr-zephyr/apps/multiapp
west flash
west dfu --storage

This puts multiapp on a XIAO ESP32S3. On its USB shell app list shows the apps and app run <name> starts one, for example app run osmosdr (apps/multiapp/README.rst). Each app also builds on its own. Releases carry the multiapp image and the SoapySDR module for gqrx and GNU Radio.

The library

• Chips: ESP32-S3 (XIAO ESP32S3), SMP or single core. ESP32-C6 (XIAO ESP32C6) and ESP32-C5 (C5-Zero): burst captures, and continuous CPU-paced receive and transmit up to 250 kS/s (esp_sdr_paced.h); the C5 also has a gapless 40 MS/s ring through the modem diagnostic bus (esp_sdr_diag.h, CONFIG_ESP_SDR_DIAG) and loops waveforms through its DAC engine at 80 or 40 MS/s (esp_sdr_replay.h, CONFIG_ESP_SDR_REPLAY). capture, rfprobe, wpan (C6) and osmosdr_serial run on them.
• Tuning: 100 to 6000 MHz in the API, but the PLL locks over a chip-specific range (about 1.8 to 2.8 GHz on the S3); below 2210 MHz through the 5/6 divider. -ERANGE when the VCO is out of range.
• Capture: 256 to 16380 samples at 80, 40 or 16 MS/s, analog low-pass filter, optional CIC decimation; gapless ring receive.
• Gain: AGC or a fixed index; the fixed gain and TX power steps use librftest.a (west blobs fetch esp-sdr-zephyr, or CONFIG_ESP_SDR_RFTEST=n).
• Transmit: sample playback at 40 or 80 MS/s, gapless streaming at 40 MS/s / n (CONFIG_ESP_SDR_TX_DAC, needs PSRAM), 18 power steps.

Chip details and quirks: doc/hardware-quirks.md. Enable it with:

CONFIG_NETWORKING=y
CONFIG_WIFI=y
CONFIG_ESP32_WIFI_STA_POWER_SAVE_NONE=y
CONFIG_ESP_SDR=y

esp_sdr_init() takes over the radio the Wi-Fi driver brought up; do not scan, connect or start an access point while using it.

Documentation

Published at https://cyber-murmel.github.io/esp-sdr-zephyr. To build it yourself:

cd esp-sdr-zephyr/doc
doxygen
make html

The site is in doc/_build_sphinx/html, with the API reference in its doxygen/ folder. CI builds it with warnings as errors (SPHINXOPTS=-W) and publishes it.

Versioning

VERSION (Zephyr's format) versions the library and the apps; each app prints it at boot. Major for breaking API changes, minor for compatible extensions, patch for fixes. A tag v<VERSION> makes a GitHub release.

Dependencies

west.yml pins:

• Zephyr esp-sdr-multiapp: ESP32-S3 SMP (zephyrproject-rtos/zephyr#120082), CDC-NCM aggregation, llext and Xtensa changes for multiapp
• hal_espressif esp-sdr: the HAL side of the SMP port
• libvrt esp-sdr: VITA 49.2
• esp-sdr (upstream, unmodified): receiver helper headers
• esp-dsp: the FFT for apps/link OFDM

License

GPL-3.0-or-later, like upstream esp-sdr; images that enable the library are subject to the GPL.