Radio

Bring-up, tuning, front end turnaround and housekeeping (esp_sdr.h). More...

Data Structures
struct	esp_sdr_iq16
struct	esp_sdr_stats

Macros
#define	ESP_SDR_FREQ_MIN_MHZ   100U
#define	ESP_SDR_SAMPLES_MIN   256U
#define	ESP_SDR_BANKS   2
#define	ESP_SDR_HIGH_RAM   __attribute__((section(".esp_sdr_high")))
#define	ESP_SDR_HIGH_BUF_DEFINE(type, name, dims, align)
#define	ESP_SDR_HIGH_STACK_DEFINE(name, size)

Enumerations
enum	esp_sdr_rate

Functions
int	esp_sdr_init (void)
	Bring the radio up and tune it to the default frequency.
int	esp_sdr_set_freq (uint32_t mhz)
	Tune the LO, shared by receive and transmit.
uint32_t	esp_sdr_get_freq (void)
int	esp_sdr_set_freq_offset (int32_t khz)
	Set a PLL offset in kHz and retune.
int	esp_sdr_set_channel_bw (unsigned int cbw)
	Set the channel bandwidth flag of the vendor tuning call (experimental).
void	esp_sdr_get_stats (struct esp_sdr_stats *stats)
int	esp_sdr_bbtop_read (unsigned int reg)
	Read or write a register of the analog baseband (I2C block 0x67), for characterization.
int	esp_sdr_set_turnaround (uint32_t settle_us, bool retune)
	Set the front end turnaround between transmit and receive.

Detailed Description

Bring-up, tuning, front end turnaround and housekeeping (esp_sdr.h).

Macro Definition Documentation

ESP_SDR_BANKS

#define ESP_SDR_BANKS   2

Dump banks available for capture and loop playback (CONFIG_ESP_SDR_BANK1 adds one).

ESP_SDR_FREQ_MIN_MHZ

#define ESP_SDR_FREQ_MIN_MHZ   100U

Software tuning limits in MHz. The PLL locks over a much narrower range that differs between chips; esp_sdr_set_freq() reports frequencies outside it with -ERANGE. Below 2210 MHz the LO goes through the 5/6 divider. Measured on one ESP32-S3: 1817 to 2793 MHz on air, 1828 to 2781 MHz without -ERANGE; on one ESP32-C6: 1774 MHz to at least 2856 MHz on air, 1784 to 2884 MHz without -ERANGE.

ESP_SDR_HIGH_BUF_DEFINE

#define ESP_SDR_HIGH_BUF_DEFINE	(		type,
			name,
			dims,
			align )

Value:

        static type name dims __aligned(align) ESP_SDR_HIGH_RAM

static type name dims __aligned(align) ESP_SDR_HIGH_RAM: an app's buffer that must be internal RAM (DMA, ring threads). A multiapp extension gets it from the host's area instead.

ESP_SDR_HIGH_RAM

#define ESP_SDR_HIGH_RAM   __attribute__((section(".esp_sdr_high")))

Place a static buffer in the internal SRAM above the capture bank (on the ESP32-S3 about 38 KiB, DMA capable). It is not zeroed at boot: buffers only. A multiapp extension defines it beforehand: it has no fixed addresses.

ESP_SDR_HIGH_STACK_DEFINE

#define ESP_SDR_HIGH_STACK_DEFINE	(		name,
			size )

Value:

        static Z_KERNEL_STACK_DEFINE_IN(name, size, ESP_SDR_HIGH_RAM)

A kernel thread stack of an app in the high region, as ESP_SDR_HIGH_BUF_DEFINE().

ESP_SDR_SAMPLES_MIN

#define ESP_SDR_SAMPLES_MIN   256U

Limits of one capture or playback burst in complex samples (one dump bank).

Enumeration Type Documentation

esp_sdr_rate

enum esp_sdr_rate

Native dump engine rates; values are the upstream protocol rate indices. The S3 receives at 80, 40 and 16 MS/s (esp_sdr_rx_rate_hz()), the C5 at 80, 40, 20, 10, 8 and 4 MS/s, the C6 at 80 MS/s only (the others return 0); the DAC runs at 80 and 40 MS/s (esp_sdr_tx_rate_hz(), S3 only).

Function Documentation

esp_sdr_bbtop_read()

int esp_sdr_bbtop_read

(

unsigned int

reg

)

Read or write a register of the analog baseband (I2C block 0x67), for characterization.

Unchecked: wrong values can detune or disable the radio until the next retune or reset.

esp_sdr_get_freq()

uint32_t esp_sdr_get_freq

(

void

)

Returns

Current LO frequency in MHz.

esp_sdr_get_stats()

void esp_sdr_get_stats

(

struct esp_sdr_stats *

stats

)

Copy the radio housekeeping counters into stats.

esp_sdr_init()

int esp_sdr_init

(

void

)

Bring the radio up and tune it to the default frequency.

Needs the Wi-Fi driver started; safe to call more than once. The radio rests in the receive state between transmissions.

Return values

0	on success.
-ENODEV	if the Wi-Fi driver is not ready.
-EIO	if a Wi-Fi call failed.

esp_sdr_set_channel_bw()

int esp_sdr_set_channel_bw

(

unsigned int

cbw

)

Set the channel bandwidth flag of the vendor tuning call (experimental).

Passed as the bandwidth argument of the PHY's channel setup; 0 (default) is the 20 MHz configuration the receiver was characterized with.

Return values

0	on success.
-EINVAL	above 2.
-EAGAIN	if esp_sdr_init() has not run.

esp_sdr_set_freq()

int esp_sdr_set_freq

(

uint32_t

mhz

)

Tune the LO, shared by receive and transmit.

Below 2210 MHz the PLL runs at 6/5 of mhz behind the 5/6 LO divider. After tuning, the PLL calibration's VCO window check decides the return value. It errs on the safe side: on the chips measured, the PLL still locked about 12 MHz beyond either end of the window.

Parameters

mhz	Frequency in MHz, ESP_SDR_FREQ_MIN_MHZ to ESP_SDR_FREQ_MAX_MHZ.

Return values

0	on success.
-EINVAL	if out of range.
-ERANGE	if the VCO ended outside its tuning window: tuned, but the PLL may not lock there.
-EAGAIN	if esp_sdr_init() has not run.

esp_sdr_set_freq_offset()

int esp_sdr_set_freq_offset

(

int32_t

khz

)

Set a PLL offset in kHz and retune.

A non-zero offset forces direct PLL tuning, also on Wi-Fi channel frequencies.

Return values

0	on success.
-ERANGE	as for esp_sdr_set_freq().
-EAGAIN	if esp_sdr_init() has not run.

esp_sdr_set_turnaround()

int esp_sdr_set_turnaround	(	uint32_t	settle_us,
		bool	retune )

Set the front end turnaround between transmit and receive.

Every switch to TX (playback, loop sessions) and back to RX waits settle_us, and with retune also reprograms the LO first. Defaults: 3000 us with retune, as after a frequency change (which always retunes and waits the full 3000 us). Shorter turnarounds suit packet links; check the signal quality at the chosen setting.

Return values

0	on success.
-EINVAL	for more than 3000 us.