Receive

Gain, analog low-pass filter, burst and decimated capture (esp_sdr_rx.h). More...

Data Structures
struct	esp_sdr_rx_burst

Macros
#define	ESP_SDR_RX_GAIN_AUTO   (-1)
#define	ESP_SDR_RX_LPF_AUTO   (-1)
#define	ESP_SDR_RX_LPF_MAX   63
#define	ESP_SDR_RX_DECIM_MIN   2U
#define	ESP_SDR_RX_FOLD_MIN   2U

Functions
int	esp_sdr_rx_set_gain (int index)
	Select hardware AGC or a fixed receive gain.
int	esp_sdr_rx_get_gain (void)
int	esp_sdr_rx_gain_max (void)
int	esp_sdr_rx_set_bandwidth (uint32_t mhz)
	Select the analog low-pass filter by approximate bandwidth.
void	esp_sdr_rx_bandwidth_range (uint32_t *min, uint32_t *max)
	Supported bandwidth range in MHz.
int	esp_sdr_rx_set_lpf (int code)
	Select a raw low-pass filter capacitor code.
int	esp_sdr_rx_get_lpf (void)
int	esp_sdr_rx_capture (enum esp_sdr_rate rate, size_t count, struct esp_sdr_rx_burst *burst)
	Capture one burst of complex samples.
int	esp_sdr_rx_capture_iq (enum esp_sdr_rate rate, size_t count, struct esp_sdr_iq16 *out, uint64_t *first_ns)
	Capture one burst and convert it to I/Q (raw units, -512 to 511) under the radio lock.
int	esp_sdr_rx_capture_bank (enum esp_sdr_rate rate, size_t count, int bank, struct esp_sdr_rx_burst *burst)
	Capture one burst into a chosen bank, like esp_sdr_rx_capture().
int	esp_sdr_rx_capture_decimated (enum esp_sdr_rate rate, size_t count, unsigned int m, struct esp_sdr_iq16 *out, size_t max_out, size_t *n_out, uint64_t *first_ns)
	Capture a burst and decimate it with a third order CIC filter.
int	esp_sdr_rx_capture_folded (enum esp_sdr_rate rate, size_t count, unsigned int n, struct esp_sdr_iq16 *out, size_t max_out, size_t *n_out, uint64_t *first_ns)
	Capture a burst and fold its spectrum by n: a power estimation mode.
uint32_t	esp_sdr_rx_rate_hz (enum esp_sdr_rate rate)
static int16_t	esp_sdr_rx_i (uint32_t word)
static int16_t	esp_sdr_rx_q (uint32_t word)
size_t	esp_sdr_rx_pack_iq8 (const uint32_t *words, size_t count, uint8_t *out)
	Pack raw words to signed 8-bit I then Q (upper 8 of 10 bits).
size_t	esp_sdr_rx_pack_iq10 (const uint32_t *words, size_t count, uint8_t *out)
	Pack raw words to the upstream packed 10-bit format.

Detailed Description

Gain, analog low-pass filter, burst and decimated capture (esp_sdr_rx.h).

Macro Definition Documentation

ESP_SDR_RX_DECIM_MIN

#define ESP_SDR_RX_DECIM_MIN   2U

Decimation factor limits for esp_sdr_rx_capture_decimated().

ESP_SDR_RX_FOLD_MIN

#define ESP_SDR_RX_FOLD_MIN   2U

Fold factor limits for esp_sdr_rx_capture_folded().

ESP_SDR_RX_GAIN_AUTO

#define ESP_SDR_RX_GAIN_AUTO   (-1)

Gain index that selects the hardware AGC.

ESP_SDR_RX_LPF_AUTO

#define ESP_SDR_RX_LPF_AUTO   (-1)

Low-pass filter code that restores the PHY-calibrated setting.

ESP_SDR_RX_LPF_MAX

#define ESP_SDR_RX_LPF_MAX   63

Largest raw low-pass filter capacitor code.

Function Documentation

esp_sdr_rx_bandwidth_range()

void esp_sdr_rx_bandwidth_range	(	uint32_t *	min,
		uint32_t *	max )

Supported bandwidth range in MHz.

Parameters

min	Set to the narrowest setting.
max	Set to the widest setting.

esp_sdr_rx_capture()

int esp_sdr_rx_capture	(	enum esp_sdr_rate	rate,
		size_t	count,
		struct esp_sdr_rx_burst *	burst )

Capture one burst of complex samples.

The samples live in a reserved SRAM bank and stay valid until the next capture or transmit session by any thread: with other radio users, copy them with esp_sdr_rx_capture_iq() instead. The caller may rewrite them in place, for example to pack them.

Parameters

rate	Native sample rate.
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
burst	Filled with the result.

Return values

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

esp_sdr_rx_capture_bank()

int esp_sdr_rx_capture_bank	(	enum esp_sdr_rate	rate,
		size_t	count,
		int	bank,
		struct esp_sdr_rx_burst *	burst )

Capture one burst into a chosen bank, like esp_sdr_rx_capture().

With two banks (CONFIG_ESP_SDR_BANK1), one burst can be processed while the next is captured into the other bank. Bank 0 is the one esp_sdr_rx_capture() uses.

Parameters

rate	Native sample rate.
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
bank	0 to ESP_SDR_BANKS - 1.
burst	Filled with the result.

Returns

Like esp_sdr_rx_capture(); -EINVAL also for a bank that does not exist.

esp_sdr_rx_capture_decimated()

int esp_sdr_rx_capture_decimated	(	enum esp_sdr_rate	rate,
		size_t	count,
		unsigned int	m,
		struct esp_sdr_iq16 *	out,
		size_t	max_out,
		size_t *	n_out,
		uint64_t *	first_ns )

Capture a burst and decimate it with a third order CIC filter.

Captures count samples like esp_sdr_rx_capture(), then (still holding the radio lock) decimates by m into out, I and Q in the usual order. The first 3 outputs (filter settling) are dropped, so up to count / m - 3 samples come out. The CIC needs no multiplies per input sample but droops towards the band edge: -2.7 dB at a quarter of the output rate, -9.3 dB at 0.45 of it. Needs CONFIG_ESP_SDR_RX_DECIM.

Parameters

rate	Native sample rate.
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
m	Decimation factor, ESP_SDR_RX_DECIM_MIN to ESP_SDR_RX_DECIM_MAX.
out	Output samples, full scale +-32767.
max_out	Capacity of out.
n_out	Set to the number of samples written.
first_ns	Set to the time of the first output sample (k_cycle_get_64() clock, ns).

Return values

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

esp_sdr_rx_capture_folded()

int esp_sdr_rx_capture_folded	(	enum esp_sdr_rate	rate,
		size_t	count,
		unsigned int	n,
		struct esp_sdr_iq16 *	out,
		size_t	max_out,
		size_t *	n_out,
		uint64_t *	first_ns )

Capture a burst and fold its spectrum by n: a power estimation mode.

Captures count samples like esp_sdr_rx_capture(), then (still holding the radio lock) sums n time-shifted blocks of count / n samples each, averaged back to the raw 10-bit scale, into out. This is decimation in frequency rather than in time: a tone originally at offset f reappears at f mod (rate / n), summed with every other tone an integer multiple of rate / n away, instead of being low-pass filtered out. The whole original band's power is represented at 1/n the data rate, so it suits a wideband power/occupancy survey; it does not suit recovering an individual signal, since two sources that land in the same fold group add instead of one of them surviving cleanly. Needs CONFIG_ESP_SDR_RX_DECIM.

Parameters

rate	Native sample rate.
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
n	Fold factor, ESP_SDR_RX_FOLD_MIN to ESP_SDR_RX_FOLD_MAX.
out	Output samples, full scale +-511 (raw 10-bit, averaged not summed).
max_out	Capacity of out.
n_out	Set to the number of samples written (count / n).
first_ns	Set to the time of the first input sample in the burst.

Return values

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

esp_sdr_rx_capture_iq()

int esp_sdr_rx_capture_iq	(	enum esp_sdr_rate	rate,
		size_t	count,
		struct esp_sdr_iq16 *	out,
		uint64_t *	first_ns )

Capture one burst and convert it to I/Q (raw units, -512 to 511) under the radio lock.

Parameters

rate	Native sample rate.
count	Complex samples, ESP_SDR_SAMPLES_MIN to ESP_SDR_SAMPLES_MAX.
out	Output samples, count of them.
first_ns	Set to the arming time (k_cycle_get_64() clock, ns).

Returns

Like esp_sdr_rx_capture().

esp_sdr_rx_gain_max()

int esp_sdr_rx_gain_max

(

void

)

Returns

Largest calibrated gain index, 0 if the PHY reports none.

esp_sdr_rx_get_gain()

int esp_sdr_rx_get_gain

(

void

)

Returns

Selected gain index, or ESP_SDR_RX_GAIN_AUTO.

esp_sdr_rx_get_lpf()

int esp_sdr_rx_get_lpf

(

void

)

Returns

Selected low-pass filter code, or ESP_SDR_RX_LPF_AUTO.

esp_sdr_rx_i()

int16_t esp_sdr_rx_i ( uint32_t word )

inlinestatic

Returns

In-phase component of a raw receive word, -512 to 511.

esp_sdr_rx_pack_iq10()

size_t esp_sdr_rx_pack_iq10	(	const uint32_t *	words,
		size_t	count,
		uint8_t *	out )

Pack raw words to the upstream packed 10-bit format.

Little-endian 20-bit I/Q pairs, two samples per five bytes. out may alias words.

Returns

Bytes written, ceil(20 * count / 8).

esp_sdr_rx_pack_iq8()

size_t esp_sdr_rx_pack_iq8	(	const uint32_t *	words,
		size_t	count,
		uint8_t *	out )

Pack raw words to signed 8-bit I then Q (upper 8 of 10 bits).

out may alias words.

Returns

Bytes written, 2 * count.

esp_sdr_rx_q()

int16_t esp_sdr_rx_q ( uint32_t word )

inlinestatic

Returns

Quadrature component of a raw receive word, -512 to 511.

esp_sdr_rx_rate_hz()

uint32_t esp_sdr_rx_rate_hz

(

enum esp_sdr_rate

rate

)

Returns

Capture sample rate in Hz, or 0 for an unknown rate.

esp_sdr_rx_set_bandwidth()

int esp_sdr_rx_set_bandwidth

(

uint32_t

mhz

)

Select the analog low-pass filter by approximate bandwidth.

Parameters

mhz	Two-sided bandwidth in MHz, 0 selects the widest setting.

Return values

0	on success.
-EINVAL	if outside the characterized range.

esp_sdr_rx_set_gain()

int esp_sdr_rx_set_gain

(

int

index

)

Select hardware AGC or a fixed receive gain.

Indices are PHY gain table entries, not dB; higher is more gain.

Parameters

index

ESP_SDR_RX_GAIN_AUTO, or 0 to esp_sdr_rx_gain_max().

Return values

0	on success.
-EINVAL	if out of range.
-ENOTSUP	for a fixed gain without CONFIG_ESP_SDR_RFTEST.
-EAGAIN	if esp_sdr_init() has not run.

esp_sdr_rx_set_lpf()

int esp_sdr_rx_set_lpf

(

int

code

)

Select a raw low-pass filter capacitor code.

Parameters

code	0 (widest) to ESP_SDR_RX_LPF_MAX, or ESP_SDR_RX_LPF_AUTO.

Return values

0	on success.
-EINVAL	if out of range.