Espressif DSP Library API Reference

Header Files

To use the library, include esp_dsp.h header file into the source code.

Signal (1D) Processing APIs

Signal processing APIs use dsps prefix. The following modules are available:

  • Dot-product - Calculates dot-product of two vectors
  • FFT - Fast Fourier Transform functionality
  • DCT - Discrete Cosine Transform functionality
  • IIR - IIR filter functionality
  • FIR - FIR filter functionality
  • Math - Basic vector operations
  • Conv - Convolution/correlation functionality
  • Support - Support functions
  • Window functions - FFT window generation functions

Dot-product

Functions

esp_err_t dsps_dotprod_s16_ansi(const int16_t *src1, const int16_t *src2, int16_t *dest, int len, int8_t shift)

dot product of two 16 bit vectors Dot product calculation for two signed 16 bit arrays: *dest += (src1[i] * src2[i]) >> (15-shift); i= [0..N) The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • src1: source array 1
  • src2: source array 2
  • dest: destination pointer
  • len: length of input arrays
  • shift: shift of the result.

esp_err_t dsps_dotprod_s16_ae32(const int16_t *src1, const int16_t *src2, int16_t *dest, int len, int8_t shift)
esp_err_t dsps_dotprod_f32_ansi(const float *src1, const float *src2, float *dest, int len)

dot product of two float vectors Dot product calculation for two floating point arrays: *dest += (src1[i] * src2[i]); i= [0..N) The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • src1: source array 1
  • src2: source array 2
  • dest: destination pointer
  • len: length of input arrays

esp_err_t dsps_dotprod_f32_ae32(const float *src1, const float *src2, float *dest, int len)
esp_err_t dsps_dotprod_f32_aes3(const float *src1, const float *src2, float *dest, int len)
esp_err_t dsps_dotprode_f32_ansi(const float *src1, const float *src2, float *dest, int len, int step1, int step2)

dot product of two float vectors with step Dot product calculation for two floating point arrays: *dest += (src1[i*step1] * src2[i*step2]); i= [0..N) The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • src1: source array 1
  • src2: source array 2
  • dest: destination pointer
  • len: length of input arrays
  • step1: step over elements in first array
  • step2: step over elements in second array

esp_err_t dsps_dotprode_f32_ae32(const float *src1, const float *src2, float *dest, int len, int step1, int step2)

Macros

dsps_dotprod_s16
dsps_dotprod_f32
dsps_dotprode_f32

FFT

Functions

esp_err_t dsps_fft2r_init_fc32(float *fft_table_buff, int table_size)

init fft tables

Initialization of Complex FFT. This function initialize coefficients table. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • ESP_ERR_DSP_PARAM_OUTOFRANGE if table_size > CONFIG_DSP_MAX_FFT_SIZE
  • ESP_ERR_DSP_REINITIALIZED if buffer already allocated internally by other function
  • One of the error codes from DSP library
Parameters
  • fft_table_buff: pointer to floating point buffer where sin/cos table will be stored if this parameter set to NULL, and table_size value is more then 0, then dsps_fft2r_init_fc32 will allocate buffer internally
  • table_size: size of the buffer in float words if fft_table_buff is NULL and table_size is not 0, buffer will be allocated internally. If table_size is 0, buffer will not be allocated.

esp_err_t dsps_fft2r_init_sc16(int16_t *fft_table_buff, int table_size)
void dsps_fft2r_deinit_fc32(void)

deinit fft tables

Free resources of Complex FFT. This function delete coefficients table if it was allocated by dsps_fft2r_init_fc32. The implementation use ANSI C and could be compiled and run on any platform

void dsps_fft2r_deinit_sc16(void)
esp_err_t dsps_fft2r_fc32_ansi_(float *data, int N, float *w)

complex FFT of radix 2

Complex FFT of radix 2 The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: input/output complex array. An elements located: Re[0], Im[0], … Re[N-1], Im[N-1] result of FFT will be stored to this array.
  • N: Number of complex elements in input array
  • w: pointer to the sin/cos table

esp_err_t dsps_fft2r_fc32_ae32_(float *data, int N, float *w)
esp_err_t dsps_fft2r_fc32_aes3_(float *data, int N, float *w)
esp_err_t dsps_fft2r_sc16_ansi_(int16_t *data, int N, int16_t *w)
esp_err_t dsps_fft2r_sc16_ae32_(int16_t *data, int N, int16_t *w)
esp_err_t dsps_fft2r_sc16_aes3_(int16_t *data, int N, int16_t *w)
esp_err_t dsps_bit_rev_fc32_ansi(float *data, int N)

bit reverse operation for the complex input array

Bit reverse operation for the complex input array The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: input/ complex array. An elements located: Re[0], Im[0], … Re[N-1], Im[N-1] result of FFT will be stored to this array.
  • N: Number of complex elements in input array

esp_err_t dsps_bit_rev_sc16_ansi(int16_t *data, int N)
esp_err_t dsps_bit_rev2r_fc32(float *data, int N)
esp_err_t dsps_gen_w_r2_fc32(float *w, int N)

Generate coefficients table for the FFT radix 2.

Generate coefficients table for the FFT radix 2. This function called inside init. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • w: memory location to store coefficients. By default coefficients will be stored to the dsps_fft_w_table_fc32. Maximum size of the FFT must be setup in menuconfig
  • N: maximum size of the FFT that will be used

esp_err_t dsps_gen_w_r2_sc16(int16_t *w, int N)
esp_err_t dsps_cplx2reC_fc32_ansi(float *data, int N)

Convert complex array to two real arrays.

Convert complex array to two real arrays in case if input was two real arrays. This function have to be used if FFT used to process real data. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: Input complex array and result of FFT2R. input has size of 2*N, because contains real and imaginary part. result will be stored to the same array. Input1: input[0..N-1], Input2: input[N..2*N-1]
  • N: Number of complex elements in input array

esp_err_t dsps_cplx2reC_sc16(int16_t *data, int N)
esp_err_t dsps_cplx2real_sc16_ansi(int16_t *data, int N)

Convert complex FFT result to real array.

Convert FFT result of complex FFT for resl input to real array. This function have to be used if FFT used to process real data. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: Input complex array and result of FFT2R. input has size of 2*N, because contains real and imaginary part. result will be stored to the same array. Input1: input[0..N-1], Input2: input[N..2*N-1]
  • N: Number of complex elements in input array

esp_err_t dsps_bit_rev_lookup_fc32_ansi(float *data, int reverse_size, uint16_t *reverse_tab)
esp_err_t dsps_bit_rev_lookup_fc32_ae32(float *data, int reverse_size, uint16_t *reverse_tab)
esp_err_t dsps_bit_rev_lookup_fc32_aes3(float *data, int reverse_size, uint16_t *reverse_tab)
esp_err_t dsps_cplx2real256_fc32_ansi(float *data)
esp_err_t dsps_gen_bitrev2r_table(int N, int step, char *name_ext)

Macros

CONFIG_DSP_MAX_FFT_SIZE
dsps_fft2r_fc32_ae32(data, N)
dsps_fft2r_fc32_aes3(data, N)
dsps_fft2r_sc16_ae32(data, N)
dsps_fft2r_sc16_aes3(data, N)
dsps_fft2r_fc32_ansi(data, N)
dsps_fft2r_sc16_ansi(data, N)
dsps_fft2r_fc32
dsps_bit_rev_fc32
dsps_cplx2reC_fc32
dsps_bit_rev_sc16
dsps_bit_rev_lookup_fc32

DCT

Functions

esp_err_t dsps_dct_f32(float *data, int N)

DCT of radix 2, unscaled.

DCT type II of radix 2, unscaled Function is FFT based The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: input/output array with size of N*2. An elements located: Re[0],Re[1], , … Re[N-1], any data… up to N*2 result of DCT will be stored to this array from 0…N-1. Size of data array must be N*2!!!
  • N: Size of DCT transform. Size of data array must be N*2!!!

esp_err_t dsps_dct_inv_f32(float *data, int N)

Inverce DCT of radix 2.

Inverce DCT type III of radix 2, unscaled Function is FFT based The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: input/output array with size of N*2. An elements located: Re[0],Re[1], , … Re[N-1], any data… up to N*2 result of DCT will be stored to this array from 0…N-1. Size of data array must be N*2!!!
  • N: Size of DCT transform. Size of data array must be N*2!!!

esp_err_t dsps_dct_f32_ref(float *data, int N, float *result)

DCTs.

Direct DCT type II and Inverce DCT type III, unscaled These functions used as a reference for general purpose. These functions are not optimyzed! The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • data: input/output array with size of N. An elements located: Re[0],Re[1], , … Re[N-1]
  • N: Size of DCT transform. Size of data array must be N*2!!!
  • result: output result array with size of N.

esp_err_t dsps_dct_inverce_f32_ref(float *data, int N, float *result)

FIR

Functions

esp_err_t dsps_16_array_rev(int16_t *arr, int16_t len)

Array reversal.

Function reverses 16-bit long array members for the purpose of the dsps_fird_s16_aes3 implementation The function has to be called either during the fir struct initialization or every time the coefficients change

Return
  • ESP_OK on success
Parameters
  • fir: pointer to the array to be reversed
  • len: length of the array to be reversed

esp_err_t dsps_fir_f32_ansi(fir_f32_t *fir, const float *input, float *output, int len)

32 bit floating point FIR filter

Function implements FIR filter The extension (_ansi) uses ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • fir: pointer to fir filter structure, that must be initialized before
  • input: input array
  • output: array with the result of FIR filter
  • len: length of input and result arrays

esp_err_t dsps_fir_f32_ae32(fir_f32_t *fir, const float *input, float *output, int len)
esp_err_t dsps_fir_f32_aes3(fir_f32_t *fir, const float *input, float *output, int len)
int dsps_fird_f32_ansi(fir_f32_t *fir, const float *input, float *output, int len)

32 bit floating point Decimation FIR filter

Function implements FIR filter with decimation The extension (_ansi) uses ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
: function returns the number of samples stored in the output array depends on the previous state value could be [0..len/decimation]
Parameters
  • fir: pointer to fir filter structure, that must be initialized before
  • input: input array
  • output: array with the result of FIR filter
  • len: length of input and result arrays

int dsps_fird_f32_ae32(fir_f32_t *fir, const float *input, float *output, int len)
int32_t dsps_fird_s16_ansi(fir_s16_t *fir, const int16_t *input, int16_t *output, int32_t len)

16 bit signed fixed point Decimation FIR filter

Function implements FIR filter with decimation The extension (_ansi) uses ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
: function returns the number of samples stored in the output array depends on the previous state value could be [0..len/decimation]
Parameters
  • fir: pointer to fir filter structure, that must be initialized before
  • input: input array
  • output: array with the result of the FIR filter
  • len: length of the result array

int32_t dsps_fird_s16_ae32(fir_s16_t *fir, const int16_t *input, int16_t *output, int32_t len)
int32_t dsps_fird_s16_aes3(fir_s16_t *fir, const int16_t *input, int16_t *output, int32_t len)
esp_err_t dsps_fir_init_f32(fir_f32_t *fir, float *coeffs, float *delay, int coeffs_len)

initialize structure for 32 bit FIR filter

Function initialize structure for 32 bit floating point FIR filter The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • fir: pointer to fir filter structure, that must be preallocated
  • coeffs: array with FIR filter coefficients. Must be length N
  • delay: array for FIR filter delay line. Must have a length = coeffs_len + 4
  • coeffs_len: FIR filter length. Length of coeffs array. For esp32s3 length should be divided by 4 and aligned to 16.

esp_err_t dsps_fird_init_f32(fir_f32_t *fir, float *coeffs, float *delay, int N, int decim, int start_pos)

initialize structure for 32 bit Decimation FIR filter Function initialize structure for 32 bit floating point FIR filter with decimation The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • fir: pointer to fir filter structure, that must be preallocated
  • coeffs: array with FIR filter coefficients. Must be length N
  • delay: array for FIR filter delay line. Must be length N
  • N: FIR filter length. Length of coeffs and delay arrays.
  • decim: decimation factor.
  • start_pos: initial value of decimation counter. Must be [0..d)

esp_err_t dsps_fird_init_s16(fir_s16_t *fir, int16_t *coeffs, int16_t *delay, int16_t coeffs_len, int16_t decim, int16_t start_pos, int16_t shift)

initialize structure for 16 bit Decimation FIR filter Function initialize structure for 16 bit signed fixed point FIR filter with decimation The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • fir: pointer to fir filter structure, that must be preallocated
  • coeffs: array with FIR filter coefficients. Must be length N
  • delay: array for FIR filter delay line. Must be length N
  • coeffs_len: FIR filter length. Length of coeffs and delay arrays.
  • decim: decimation factor.
  • start_pos: initial value of decimation counter. Must be [0..d)
  • shift: shift position of the result

esp_err_t dsps_fird_s16_aexx_free(fir_s16_t *fir)

support arrays freeing function

Function frees all the arrays, which were created during the initialization of the fir_s16_t structure

  1. frees allocated memory for rounding buffer, for the purposes of esp32s3 ee.ld.accx.ip assembly instruction
  2. frees allocated memory in case the delay line is NULL
  3. frees allocated memory in case the length of the filter (and the delay line) is not divisible by 8 and new delay line and filter coefficients arrays are created for the purpose of the esp32s3 assembly

Return
  • ESP_OK on success
Parameters
  • fir: pointer to fir filter structure, that must be initialized before

esp_err_t dsps_fir_f32_free(fir_f32_t *fir)

support arrays freeing function

Function frees the delay line arrays, if it was allocated by the init functions.

Return
  • ESP_OK on success
Parameters
  • fir: pointer to fir filter structure, that must be initialized before

Structures

struct fir_f32_s

Data struct of f32 fir filter.

This structure is used by a filter internally. A user should access this structure only in case of extensions for the DSP Library. All fields of this structure are initialized by the dsps_fir_init_f32(…) function.

Public Members

float *coeffs

Pointer to the coefficient buffer.

float *delay

Pointer to the delay line buffer.

int N

FIR filter coefficients amount.

int pos

Position in delay line.

int decim

Decimation factor.

int d_pos

Actual decimation counter.

int16_t use_delay

The delay line was allocated by init function.

struct fir_s16_s

Data struct of s16 fir filter.

This structure is used by a filter internally. A user should access this structure only in case of extensions for the DSP Library. All fields of this structure are initialized by the dsps_fir_init_s16(…) function.

Public Members

int16_t *coeffs

Pointer to the coefficient buffer.

int16_t *delay

Pointer to the delay line buffer.

int16_t coeffs_len

FIR filter coefficients amount.

int16_t pos

Position in delay line.

int16_t decim

Decimation factor.

int16_t d_pos

Actual decimation counter.

int16_t shift

Shift value of the result.

int32_t *rounding_buff

Rounding buffer for the purposes of esp32s3 ee.ld.accx.ip assembly instruction

int32_t rounding_val

Rounding value

int16_t free_status

Indicator for dsps_fird_s16_aes3_free() function

Macros

dsps_fir_f32
dsps_fird_f32
dsps_fird_s16

Type Definitions

typedef struct fir_f32_s fir_f32_t

Data struct of f32 fir filter.

This structure is used by a filter internally. A user should access this structure only in case of extensions for the DSP Library. All fields of this structure are initialized by the dsps_fir_init_f32(…) function.

typedef struct fir_s16_s fir_s16_t

Data struct of s16 fir filter.

This structure is used by a filter internally. A user should access this structure only in case of extensions for the DSP Library. All fields of this structure are initialized by the dsps_fir_init_s16(…) function.

IIR

Functions

esp_err_t dsps_biquad_gen_lpf_f32(float *coeffs, float f, float qFactor)

LPF IIR filter coefficients Coefficients for low pass 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter cut off frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_hpf_f32(float *coeffs, float f, float qFactor)

HPF IIR filter coefficients.

Coefficients for high pass 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter cut off frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_bpf_f32(float *coeffs, float f, float qFactor)

BPF IIR filter coefficients.

Coefficients for band pass 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter center frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_bpf0db_f32(float *coeffs, float f, float qFactor)

0 dB BPF IIR filter coefficients

Coefficients for band pass 2nd order IIR filter (bi-quad) with 0 dB gain in passband The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter center frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_notch_f32(float *coeffs, float f, float gain, float qFactor)

Notch IIR filter coefficients.

Coefficients for notch 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • gain: gain in stopband in dB
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_allpass360_f32(float *coeffs, float f, float qFactor)

Allpass 360 degree IIR filter coefficients.

Coefficients for all pass 2nd order IIR filter (bi-quad) with 360 degree phase shift The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_allpass180_f32(float *coeffs, float f, float qFactor)

Allpass 180 degree IIR filter coefficients.

Coefficients for all pass 2nd order IIR filter (bi-quad) with 180 degree phase shift The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_peakingEQ_f32(float *coeffs, float f, float qFactor)

peak IIR filter coefficients

Coefficients for peak 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_lowShelf_f32(float *coeffs, float f, float gain, float qFactor)

low shelf IIR filter coefficients

Coefficients for low pass Shelf 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • gain: gain in stopband in dB
  • qFactor: Q factor of filter

esp_err_t dsps_biquad_gen_highShelf_f32(float *coeffs, float f, float gain, float qFactor)

high shelf IIR filter coefficients

Coefficients for high pass Shelf 2nd order IIR filter (bi-quad) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • coeffs: result coefficients. b0,b1,b2,a1,a2, a0 are not placed to the array and expected by IIR as 1
  • f: filter notch frequency in range of 0..0.5 (normalized to sample frequency)
  • gain: gain in stopband in dB
  • qFactor: Q factor of filter

Functions

esp_err_t dsps_biquad_f32_ansi(const float *input, float *output, int len, float *coef, float *w)

IIR filter.

IIR filter 2nd order direct form II (bi quad) The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input: input array
  • output: output array
  • len: length of input and output vectors
  • coef: array of coefficients. b0,b1,b2,a1,a2 expected that a0 = 1. b0..b2 - numerator, a0..a2 - denominator
  • w: delay line w0,w1. Length of 2.

esp_err_t dsps_biquad_f32_ae32(const float *input, float *output, int len, float *coef, float *w)
esp_err_t dsps_biquad_f32_aes3(const float *input, float *output, int len, float *coef, float *w)

Macros

dsps_biquad_f32

Math

Functions

esp_err_t dsps_add_f32_ansi(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)

add two arrays

The function add one input array to another out[i*step_out] = input1[i*step1] + input2[i*step2]; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input1: input array 1
  • input2: input array 2
  • output: output array
  • len: amount of operations for arrays
  • step1: step over input array 1 (by default should be 1)
  • step2: step over input array 2 (by default should be 1)
  • step_out: step over output array (by default should be 1)

esp_err_t dsps_add_f32_ae32(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)
esp_err_t dsps_add_s16_ansi(const int16_t *input1, const int16_t *input2, int16_t *output, int len, int step1, int step2, int step_out, int shift)
esp_err_t dsps_add_s16_ae32(const int16_t *input1, const int16_t *input2, int16_t *output, int len, int step1, int step2, int step_out, int shift)

Macros

dsps_add_f32
dsps_add_s16

Functions

esp_err_t dsps_sub_f32_ansi(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)

sub arrays

The function subtract one array from another out[i*step_out] = input1[i*step1] - input2[i*step2]; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input1: input array 1
  • input2: input array 2
  • output: output array
  • len: amount of operations for arrays
  • step1: step over input array 1 (by default should be 1)
  • step2: step over input array 2 (by default should be 1)
  • step_out: step over output array (by default should be 1)

esp_err_t dsps_sub_f32_ae32(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)

Macros

dsps_sub_f32

Functions

esp_err_t dsps_mul_f32_ansi(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)

Multiply two arrays.

The function multiply one input array to another and store result to other array out[i*step_out] = input1[i*step1] * input2[i*step2]; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input1: input array 1
  • input2: input array 2
  • output: output array
  • len: amount of operations for arrays
  • step1: step over input array 1 (by default should be 1)
  • step2: step over input array 2 (by default should be 1)
  • step_out: step over output array (by default should be 1)

esp_err_t dsps_mul_f32_ae32(const float *input1, const float *input2, float *output, int len, int step1, int step2, int step_out)
esp_err_t dsps_mul_s16_ansi(const int16_t *input1, const int16_t *input2, int16_t *output, int len, int step1, int step2, int step_out, int shift)

Multiply two arrays.

The function multiply one input array to another and store result to other array out[i*step_out] = input1[i*step1] * input2[i*step2]; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input1: input array 1
  • input2: input array 2
  • output: output array
  • len: amount of operations for arrays
  • step1: step over input array 1 (by default should be 1)
  • step2: step over input array 2 (by default should be 1)
  • step_out: step over output array (by default should be 1)
  • shift: output shift after multiplication (by default should be 15)

Macros

dsps_mul_f32
dsps_mul_s16

Functions

esp_err_t dsps_addc_f32_ansi(const float *input, float *output, int len, float C, int step_in, int step_out)

add constant

The function adds constant to the input array x[i*step_out] = y[i*step_in] + C; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input: input array
  • output: output array
  • len: amount of operations for arrays
  • C: constant value
  • step_in: step over input array (by default should be 1)
  • step_out: step over output array (by default should be 1)

esp_err_t dsps_addc_f32_ae32(const float *input, float *output, int len, float C, int step_in, int step_out)

Macros

dsps_addc_f32

Functions

esp_err_t dsps_mulc_f32_ansi(const float *input, float *output, int len, float C, int step_in, int step_out)

multiply constant

The function multiplies input array to the constant value x[i*step_out] = y[i*step_in]*C; i=[0..len) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • input: input array
  • output: output array
  • len: amount of operations for arrays
  • C: constant value
  • step_in: step over input array (by default should be 1)
  • step_out: step over output array (by default should be 1)

esp_err_t dsps_mulc_f32_ae32(const float *input, float *output, int len, float C, int step_in, int step_out)
esp_err_t dsps_mulc_s16_ae32(const int16_t *input, int16_t *output, int len, int16_t C, int step_in, int step_out)
esp_err_t dsps_mulc_s16_ansi(const int16_t *input, int16_t *output, int len, int16_t C, int step_in, int step_out)

Macros

dsps_mulc_f32
dsps_mulc_s16

Conv

Functions

esp_err_t dsps_conv_f32_ae32(const float *Signal, const int siglen, const float *Kernel, const int kernlen, float *convout)

Convolution.

The function convolve Signal array with Kernel array. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • Signal: input array with signal
  • siglen: length of the input signal
  • Kernel: input array with convolution kernel
  • kernlen: length of the Kernel array
  • convout: output array with convolution result length of (siglen + Kernel -1)

esp_err_t dsps_conv_f32_ansi(const float *Signal, const int siglen, const float *Kernel, const int kernlen, float *convout)

Macros

dsps_conv_f32

Functions

esp_err_t dsps_corr_f32_ansi(const float *Signal, const int siglen, const float *Pattern, const int patlen, float *dest)

Correlation with pattern.

The function correlate input sigla array with pattern array. The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library (one of the input array are NULL, or if (siglen < patlen))
Parameters
  • Signal: input array with signal values
  • siglen: length of the signal array
  • Pattern: input array with pattern values
  • patlen: length of the pattern array. The siglen must be bigger then patlen!
  • dest: output array with result of correlation

esp_err_t dsps_corr_f32_ae32(const float *Signal, const int siglen, const float *Pattern, const int patlen, float *dest)

Macros

dsps_corr_f32

Support

Functions

esp_err_t dsps_d_gen_f32(float *output, int len, int pos)

delta function

The function generate delta function. output[i]=0, if i=[0..N) output[i]=1, if i=pos, pos: [0..N-1) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • output: output array.
  • len: length of the input signal
  • pos: delta function position

Functions

esp_err_t dsps_h_gen_f32(float *output, int len, int pos)

Heviside function.

The Heviside function. output[i]=0, if i=[0..pos) output[i]=1, if i=[pos..N) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • output: output array.
  • len: length of the input signal
  • pos: heviside function position

Functions

esp_err_t dsps_tone_gen_f32(float *output, int len, float Ampl, float freq, float phase)

tone

The function generate a tone signal. x[i]=A*sin(2*PI*i + ph/180*PI) The implementation use ANSI C and could be compiled and run on any platform

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • output: output array.
  • len: length of the input signal
  • Ampl: amplitude
  • freq: Naiquist frequency -1..1
  • phase: phase in degree

Functions

void dsps_view(const float *data, int32_t len, int width, int height, float min, float max, char view_char)

plot view

Generic view function. This function takes input samples and show then in console view as a plot. The main purpose to give and draft debug information to the DSP developer.

Parameters
  • data: array with input samples.
  • len: length of the input array
  • width: plot width in symbols
  • height: plot height in lines
  • min: minimum value that will be limited by Axis Y.
  • max: maximum value that will be limited by Axis Y.
  • view_char: character to draw the plot calues (‘.’ or ‘|’ etc)

void dsps_view_s16(const int16_t *data, int32_t len, int width, int height, float min, float max, char view_char)
void dsps_view_spectrum(const float *data, int32_t len, float min, float max)

spectrum view

The view function to show spectrum values in 64x10 screen. The function based on dsps_view.

Parameters
  • data: array with input samples.
  • len: length of the input array
  • min: minimum value that will be limited by Axis Y.
  • max: maximum value that will be limited by Axis Y.

Functions

float dsps_snr_f32(const float *input, int32_t len, uint8_t use_dc)

SNR.

The function calculates signal to noise ration in case if signal is sine tone. The function makes FFT of the input, then search a spectrum maximum, and then calculated SNR as sum of all harmonics to the maximum value. This function have to be used for debug and unit tests only. It’s not optimized for real-time processing. The implementation use ANSI C and could be compiled and run on any platform

Return
  • SNR in dB
Parameters
  • input: input array.
  • len: length of the input signal
  • use_dc: this parameter define will be DC value used for calculation or not. 0 - SNR will not include DC power 1 - SNR will include DC power

float dsps_snr_fc32(const float *input, int32_t len)

Functions

float dsps_sfdr_f32(const float *input, int32_t len, int8_t use_dc)

SFDR.

The function calculates Spurious-Free Dynamic Range. The function makes FFT of the input, then search a spectrum maximum, and then compare maximum value with all others. Result calculated as minimum value. This function have to be used for debug and unit tests only. It’s not optimized for real-time processing. The implementation use ANSI C and could be compiled and run on any platform

Return
  • SFDR in DB
Parameters
  • input: input array.
  • len: length of the input signal
  • use_dc: this parameter define will be DC value used for calculation or not. 0 - SNR will not include DC power 1 - SNR will include DC power

float dsps_sfdr_fc32(const float *input, int32_t len)

Window Functions

Functions

void dsps_wind_hann_f32(float *window, int len)

Hann window.

The function generates Hann window.

Parameters
  • window: buffer to store window array.
  • len: length of the window array

Matrix Operations APIs

Matrix operations APIs use dspm prefix. The following modules are available:

  • Multiplication - basic matrix multiplication operations

Matrix Multiplication

Functions

esp_err_t dspm_mult_f32_ansi(const float *A, const float *B, float *C, int m, int n, int k)

Matrix multiplication.

Matrix multiplication for two floating point matrices: C[m][k] = A[m][n] * B[n][k] The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[m][n]
  • B: input matrix B[n][k]
  • C: result matrix C[m][k]
  • m: matrix dimension
  • n: matrix dimension
  • k: matrix dimension

esp_err_t dspm_mult_f32_ae32(const float *A, const float *B, float *C, int m, int n, int k)
esp_err_t dspm_mult_f32_aes3(const float *A, const float *B, float *C, int m, int n, int k)
esp_err_t dspm_mult_s16_ansi(const int16_t *A, const int16_t *B, int16_t *C, int m, int n, int k, int shift)

Matrix multiplication 16 bit signeg int.

Matrix multiplication for two signed 16 bit fixed point matrices: C[m][k] = (A[m][n] * B[n][k]) >> (15- shift) The extension (_ansi) use ANSI C and could be compiled and run on any platform. The extension (_ae32) is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[m][n]
  • B: input matrix B[n][k]
  • C: result matrix C[m][k]
  • m: matrix dimension
  • n: matrix dimension
  • k: matrix dimension
  • shift: every result will be shifted and stored as 16 bit signed value.

esp_err_t dspm_mult_s16_ae32(const int16_t *A, const int16_t *B, int16_t *C, int m, int n, int k, int shift)
esp_err_t dspm_mult_s16_aes3(const int16_t *A, const int16_t *B, int16_t *C, int m, int n, int k, int shift)
esp_err_t dspm_mult_3x3x1_f32_ae32(const float *A, const float *B, float *C)

Matrix multiplication A[3x3]xB[3x1].

Matrix multiplication for two floating point matrices 3x3 and 3x1: C[1][3] = A[3][3] * B[3][1] The implementation is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[3][3]
  • B: input matrix/vector B[3][1]
  • C: result matrix/vector C[3][3]

esp_err_t dspm_mult_3x3x3_f32_ae32(const float *A, const float *B, float *C)

Matrix multiplication A[3x3]xB[3x3].

Matrix multiplication for two square 3x3 floating point matrices: C[3][3] = A[3][3] * B[3][3] The implementation is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[3][3]
  • B: input matrix B[3][3]
  • C: result matrix C[3][3]

esp_err_t dspm_mult_4x4x1_f32_ae32(const float *A, const float *B, float *C)

Matrix multiplication A[4x4]xB[4x1].

Matrix multiplication for two floating point matrices 4x4 and 4x1: C[1][4] = A[4][4] * B[4][1] The implementation is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[4][4]
  • B: input matrix/vector B[4][1]
  • C: result matrix/vector C[4][4]

esp_err_t dspm_mult_4x4x4_f32_ae32(const float *A, const float *B, float *C)

Matrix multiplication A[4x4]xB[4x4].

Matrix multiplication for two square 3x3 floating point matrices: C[4][4] = A[4][4] * B[4][4] The implementation is optimized for ESP32 chip.

Return
  • ESP_OK on success
  • One of the error codes from DSP library
Parameters
  • A: input matrix A[4][4]
  • B: input matrix B[4][4]
  • C: result matrix C[4][4]

Macros

dspm_mult_s16
dspm_mult_f32
dspm_mult_3x3x1_f32(A, B, C)
dsps_sub_f32
dsps_add_f32
dspm_mult_4x4x4_f32(A, B, C)

Matrix Operations

Miscellaneous

Various common functions used by other modules are included in this module.

Common APIs

Functions

bool dsp_is_power_of_two(int x)

check power of two The function check if the argument is power of 2. The implementation use ANSI C and could be compiled and run on any platform

Return
  • true if x is power of two
  • false if no

int dsp_power_of_two(int x)

Power of two The function return power of 2 for values 2^N. The implementation use ANSI C and could be compiled and run on any platform.

Return
  • power of two

esp_err_t tie_log(int n_regs, ...)

Logginng for esp32s3 TIE core Registers covered q0 to q7, ACCX and SAR_BYTE.

Return
ESP_OK
Parameters
  • n_regs: number of registers to be logged at once
  • ...: register codes 0, 1, 2, 3, 4, 5, 6, 7, ‘a’, ‘s’

Macros

dsp_get_cpu_cycle_count