Transmit

Power steps, one-shot and loop playback, sweeps and streaming (esp_sdr_tx.h). More...

Topics
	Loop playback

Data Structures
struct	esp_sdr_tx_sweep_stats
struct	esp_sdr_tx_backend
struct	esp_sdr_tx_stats
struct	esp_sdr_tx_dac_stats

Macros
#define	ESP_SDR_TX_PLAY_MAX_MS   5000U

Typedefs
typedef void(*	esp_sdr_tx_dac_gen_t) (void *user, uint32_t *dst, uint64_t index, uint32_t n)

Functions
int	esp_sdr_tx_set_gain (int index)
	Select a transmit power step, picked up by the next transmission.
int	esp_sdr_tx_get_gain (void)
int	esp_sdr_tx_gain_max (void)
int	esp_sdr_tx_gain_power (int index)
int	esp_sdr_tx_set_lpf (int code_a, int code_b)
	Select the TX baseband low-pass capacitor codes (experimental).
uint32_t	esp_sdr_tx_rate_hz (enum esp_sdr_rate rate)
static uint32_t	esp_sdr_tx_word (int16_t i, int16_t q)
int	esp_sdr_tx_play (enum esp_sdr_rate rate, const uint32_t *words, size_t count)
	Play one burst of complex samples out through the TX DAC.
int	esp_sdr_tx_play_for (enum esp_sdr_rate rate, const uint32_t *words, size_t count, uint32_t duration_ms, uint32_t *bursts)
	Replay one burst back to back for a while, like esp_sdr_tx_play().
int	esp_sdr_tx_sweep (enum esp_sdr_rate rate, float f0_hz, float f1_hz, uint32_t duration_ms, int amp, struct esp_sdr_tx_sweep_stats *stats)
	Transmit a linear frequency sweep at fixed power.
int	esp_sdr_tx_set_backend (const struct esp_sdr_tx_backend *backend)
	Select the streaming backend; NULL restores the default (DAC if built, else the stub).
const struct esp_sdr_tx_backend *	esp_sdr_tx_get_backend (void)
int	esp_sdr_tx_start (uint64_t freq_hz, uint32_t rate_hz)
	Start streaming.
int	esp_sdr_tx_write (const struct esp_sdr_iq16 *samples, size_t count)
	Hand samples to the backend.
int	esp_sdr_tx_stop (void)
	Stop streaming; no-op when stopped.
bool	esp_sdr_tx_active (void)
void	esp_sdr_tx_get_stats (struct esp_sdr_tx_stats *stats)
void	esp_sdr_tx_dac_get_stats (struct esp_sdr_tx_dac_stats *stats)
int	esp_sdr_tx_dac_play_gen (esp_sdr_tx_dac_gen_t gen, void *user, uint64_t samples)
	Play samples generated DAC samples gapless at the current LO.
uint32_t	esp_sdr_tx_dac_queued (void)

Variables
const struct esp_sdr_tx_backend	esp_sdr_tx_stub_backend
const struct esp_sdr_tx_backend	esp_sdr_tx_dac_backend

Detailed Description

Power steps, one-shot and loop playback, sweeps and streaming (esp_sdr_tx.h).

Macro Definition Documentation

ESP_SDR_TX_PLAY_MAX_MS

#define ESP_SDR_TX_PLAY_MAX_MS   5000U

Longest esp_sdr_tx_play_for() duration; the caller's thread busy-waits throughout.

Typedef Documentation

esp_sdr_tx_dac_gen_t

typedef void(* esp_sdr_tx_dac_gen_t) (void *user, uint32_t *dst, uint64_t index, uint32_t n)

Waveform source for esp_sdr_tx_dac_play_gen(): write n DAC words (esp_sdr_tx_word()) for output samples [index, index + n) at the 40 MS/s DAC rate. Runs in the filler, ahead of the air by up to two banks, with interrupts locked when the vector interpolator is built (CONFIG_ESP_SDR_TX_DAC_SIMD) and unlocked otherwise: table lookups and copies only, from IRAM.

Function Documentation

esp_sdr_tx_active()

bool esp_sdr_tx_active

(

void

)

Returns

Whether streaming is started.

esp_sdr_tx_dac_get_stats()

void esp_sdr_tx_dac_get_stats

(

struct esp_sdr_tx_dac_stats *

stats

)

Copy the DAC backend statistics into stats.

esp_sdr_tx_dac_play_gen()

int esp_sdr_tx_dac_play_gen	(	esp_sdr_tx_dac_gen_t	gen,
		void *	user,
		uint64_t	samples )

Play samples generated DAC samples gapless at the current LO.

Returns once the last sample has played, about 1.5 ms after the call plus the waveform's duration. Not while the backend streams.

Return values

0	on success.
-EINVAL	without a generator or samples.
-EBUSY	while the backend streams or plays.
-EIO	if the session could not start or was stopped, or a block was filled late: the waveform is cut off at that point (a late block ends the session with a block of silence, it is not resumed).

esp_sdr_tx_dac_queued()

uint32_t esp_sdr_tx_dac_queued

(

void

)

Returns

Input samples written but not yet interpolated for the DAC: what a writer adds to the latency. Keep it below the ring size (CONFIG_ESP_SDR_TX_DAC_RING_SAMPLES), or new input overwrites old.

esp_sdr_tx_gain_max()

int esp_sdr_tx_gain_max

(

void

)

Returns

Strongest transmit power step.

esp_sdr_tx_gain_power()

int esp_sdr_tx_gain_power

(

int

index

)

Returns

The vendor's target power for index in quarter dB (relative, not dBm; measured 4.24 units per dB over the ladder), INT_MIN if out of range.

esp_sdr_tx_get_backend()

const struct esp_sdr_tx_backend * esp_sdr_tx_get_backend

(

void

)

Returns

The selected streaming backend.

esp_sdr_tx_get_gain()

int esp_sdr_tx_get_gain

(

void

)

Returns

Selected transmit power step.

esp_sdr_tx_get_stats()

void esp_sdr_tx_get_stats

(

struct esp_sdr_tx_stats *

stats

)

Copy the streaming statistics into stats.

esp_sdr_tx_play()

int esp_sdr_tx_play	(	enum esp_sdr_rate	rate,
		const uint32_t *	words,
		size_t	count )

Play one burst of complex samples out through the TX DAC.

Reverse direction of esp_sdr_rx_capture(): drives the dump engine's DAC side through the same shared SRAM bank. Swaps the analog front end to TX for the duration and restores RX afterwards. The caller must still have RF safety in place (dummy load / attenuated link); this function does not limit transmit power beyond the weakest default step.

The DAC side has its own clock: only ESP_SDR_RATE_40MSPS and ESP_SDR_RATE_80MSPS exist, see esp_sdr_tx_rate_hz().

Parameters

rate	Transmit sample rate.
words	Complex samples built with esp_sdr_tx_word().
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.

Return values

0	on success.
-EINVAL	for an unsupported rate or count.
-EAGAIN	if esp_sdr_init() has not run.
-ETIMEDOUT	if the dump engine did not finish.

esp_sdr_tx_play_for()

int esp_sdr_tx_play_for	(	enum esp_sdr_rate	rate,
		const uint32_t *	words,
		size_t	count,
		uint32_t	duration_ms,
		uint32_t *	bursts )

Replay one burst back to back for a while, like esp_sdr_tx_play().

Switches the front end once and retriggers the DAC until duration_ms has passed (0: exactly one burst). With a duration, words is tiled over as much of the bank as whole copies fit, so each retrigger (~1.35 us gap) comes after up to ESP_SDR_SAMPLES_MAX samples. Seamless only if words holds a whole number of signal periods. Holds the radio lock throughout, so captures wait.

Parameters

rate	Transmit sample rate.
words	Complex samples built with esp_sdr_tx_word().
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
duration_ms	0 to ESP_SDR_TX_PLAY_MAX_MS.
bursts	If not NULL, set to the number of bursts played.

Return values

0	on success.
-EINVAL	for an unsupported rate, count or duration.
-EAGAIN	if esp_sdr_init() has not run.
-ETIMEDOUT	if the dump engine did not finish a burst.

esp_sdr_tx_rate_hz()

uint32_t esp_sdr_tx_rate_hz

(

enum esp_sdr_rate

rate

)

Returns

DAC sample rate in Hz, or 0 if the DAC cannot run at rate.

esp_sdr_tx_set_backend()

int esp_sdr_tx_set_backend

(

const struct esp_sdr_tx_backend *

backend

)

Select the streaming backend; NULL restores the default (DAC if built, else the stub).

Return values

0	on success.
-EBUSY	while transmitting.

esp_sdr_tx_set_gain()

int esp_sdr_tx_set_gain

(

int

index

)

Select a transmit power step, picked up by the next transmission.

Steps follow the vendor PHY's TX power ladder (gain memory index plus baseband gain code per step). TX has no AGC, so there is no "auto" step.

Parameters

index

0 (weakest) to esp_sdr_tx_gain_max() (strongest).

Return values

0	on success.
-EINVAL	if out of range.
-ENOTSUP	without CONFIG_ESP_SDR_RFTEST.

esp_sdr_tx_set_lpf()

int esp_sdr_tx_set_lpf	(	int	code_a,
		int	code_b )

Select the TX baseband low-pass capacitor codes (experimental).

The two code pairs the vendor PHY calibrates for transmit (inferred from its TX setup; larger is narrower, as on the receive side). Written at once and kept across retunes.

Parameters

code_a,code_b

0 to ESP_SDR_RX_LPF_MAX, or ESP_SDR_RX_LPF_AUTO for the PHY's code.

Return values

0	on success.
-EINVAL	if out of range.

esp_sdr_tx_start()

int esp_sdr_tx_start	(	uint64_t	freq_hz,
		uint32_t	rate_hz )

Start streaming.

Return values

0	on success.
-EALREADY	if already started.
-EINVAL	for a zero rate.

esp_sdr_tx_sweep()

int esp_sdr_tx_sweep	(	enum esp_sdr_rate	rate,
		float	f0_hz,
		float	f1_hz,
		uint32_t	duration_ms,
		int	amp,
		struct esp_sdr_tx_sweep_stats *	stats )

Transmit a linear frequency sweep at fixed power.

Frequency goes linearly from f0_hz to f1_hz (constant Hz per second) over duration_ms of wall-clock time, at the selected transmit step (esp_sdr_tx_set_gain()) and digital amplitude amp. Each segment of up to ESP_SDR_SAMPLES_MAX samples is synthesized into the bank while the DAC is idle, so transmission pauses between segments; phase follows absolute time, so the chirp stays continuous across the pauses. Holds the radio lock throughout.

Parameters

rate	Transmit sample rate, see esp_sdr_tx_rate_hz().
f0_hz,f1_hz	Baseband offsets from the LO, below half the rate.
duration_ms	1 to ESP_SDR_TX_PLAY_MAX_MS.
amp	Digital amplitude 1 to 511; the TX baseband compresses near 511.
stats	If not NULL, filled with what was played.

Return values

0	on success.
-EINVAL	for an unsupported rate, frequency, duration or amplitude.
-EAGAIN	if esp_sdr_init() has not run.
-ETIMEDOUT	if the dump engine did not finish a burst.

esp_sdr_tx_word()

uint32_t esp_sdr_tx_word ( int16_t i, int16_t q )

inlinestatic

Returns

Raw transmit word for esp_sdr_tx_play(): I in bits 9:0, Q in bits 19:10.

esp_sdr_tx_write()

int esp_sdr_tx_write	(	const struct esp_sdr_iq16 *	samples,
		size_t	count )

Hand samples to the backend.

Returns

Samples taken, or a negative errno (-ENOTCONN when not started).

Variable Documentation

esp_sdr_tx_dac_backend

const struct esp_sdr_tx_backend esp_sdr_tx_dac_backend

extern

DAC backend: interpolates the input linearly to 40 MS/s and plays it. The input rate must divide 40 MS/s by at least 2 and the frequency must be a whole MHz (it retunes the shared LO, so the receiver moves too). Output is gapless while the fill keeps up; input that is not there in time plays as zeros.

esp_sdr_tx_stub_backend

const struct esp_sdr_tx_backend esp_sdr_tx_stub_backend

extern

Backend that consumes and counts samples, for tests.