I2S¶
概述¶
ESP32 contains two I2S peripherals. These peripherals can be configured to input and output sample data via the I2S driver.
The I2S peripheral supports DMA meaning it can stream sample data without requiring each sample to be read or written by the CPU.
I2S output can also be routed directly to the Digital/Analog Converter output channels (GPIO 25 & GPIO 26) to produce analog output directly, rather than via an external I2S codec.
应用程序示例¶
A full I2S example is available in esp-idf: peripherals/i2s.
Short example of I2S configuration:
#include "driver/i2s.h"
#include "freertos/queue.h"
static const int i2s_num = 0; // i2s port number
static const i2s_config_t i2s_config = {
.mode = I2S_MODE_MASTER | I2S_MODE_TX,
.sample_rate = 44100,
.bits_per_sample = 16,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_I2S | I2S_COMM_FORMAT_I2S_MSB,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
.dma_buf_count = 8,
.dma_buf_len = 64
};
static const i2s_pin_config_t pin_config = {
.bck_io_num = 26,
.ws_io_num = 25,
.data_out_num = 22,
.data_in_num = I2S_PIN_NO_CHANGE
};
...
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver
i2s_set_pin(i2s_num, &pin_config);
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
Short example configuring I2S to use internal DAC for analog output:
#include "driver/i2s.h"
#include "freertos/queue.h"
static const int i2s_num = 0; // i2s port number
static const i2s_config_t i2s_config = {
.mode = I2S_MODE_MASTER | I2S_MODE_TX | I2S_MODE_DAC_BUILT_IN,
.sample_rate = 44100,
.bits_per_sample = 8, /* must be 8 for built-in DAC */
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_I2S_MSB,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1, // high interrupt priority
.dma_buf_count = 8,
.dma_buf_len = 64
};
...
i2s_driver_install(i2s_num, &i2s_config, 0, NULL); //install and start i2s driver
i2s_set_pin(i2s_num, NULL); //for internal DAC
i2s_set_sample_rates(i2s_num, 22050); //set sample rates
i2s_driver_uninstall(i2s_num); //stop & destroy i2s driver
API 参考手册¶
头文件¶
- components/driver/include/driver/i2s.h
Data 结构体¶
- struct
i2s_config_t
¶I2S configuration parameters for i2s_param_config function.
Public Members
- i2s_mode_t
mode
¶I2S work mode
- int
sample_rate
¶I2S sample rate
- i2s_bits_per_sample_t
bits_per_sample
¶I2S bits per sample
- i2s_channel_fmt_t
channel_format
¶I2S channel format
- i2s_comm_format_t
communication_format
¶I2S communication format
- int
intr_alloc_flags
¶Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info
- int
dma_buf_count
¶I2S DMA Buffer Count
- int
dma_buf_len
¶I2S DMA Buffer Length
- struct
i2s_event_t
¶Event structure used in I2S event queue.
- struct
i2s_pin_config_t
¶I2S pin number for i2s_set_pin.
宏¶
I2S_PIN_NO_CHANGE
¶Use in i2s_pin_config_t for pins which should not be changed
枚举¶
- enum
i2s_bits_per_sample_t
¶I2S bit width per sample.
Values:
I2S_BITS_PER_SAMPLE_8BIT
= 8¶I2S bits per sample: 8-bits
I2S_BITS_PER_SAMPLE_16BIT
= 16¶I2S bits per sample: 16-bits
I2S_BITS_PER_SAMPLE_24BIT
= 24¶I2S bits per sample: 24-bits
I2S_BITS_PER_SAMPLE_32BIT
= 32¶I2S bits per sample: 32-bits
- enum
i2s_comm_format_t
¶I2S communication standard format.
Values:
I2S_COMM_FORMAT_I2S
= 0x01¶I2S communication format I2S
I2S_COMM_FORMAT_I2S_MSB
= 0x02¶I2S format MSB
I2S_COMM_FORMAT_I2S_LSB
= 0x04¶I2S format LSB
I2S_COMM_FORMAT_PCM
= 0x08¶I2S communication format PCM
I2S_COMM_FORMAT_PCM_SHORT
= 0x10¶PCM Short
I2S_COMM_FORMAT_PCM_LONG
= 0x20¶PCM Long
- enum
i2s_channel_fmt_t
¶I2S channel format type.
Values:
I2S_CHANNEL_FMT_RIGHT_LEFT
= 0x00¶
I2S_CHANNEL_FMT_ALL_RIGHT
¶
I2S_CHANNEL_FMT_ALL_LEFT
¶
I2S_CHANNEL_FMT_ONLY_RIGHT
¶
I2S_CHANNEL_FMT_ONLY_LEFT
¶
- enum
pdm_sample_rate_ratio_t
¶PDM sample rate ratio, measured in Hz.
Values:
PDM_SAMPLE_RATE_RATIO_64
¶
PDM_SAMPLE_RATE_RATIO_128
¶
- enum
pdm_pcm_conv_t
¶PDM PCM convter enable/disable.
Values:
PDM_PCM_CONV_ENABLE
¶
PDM_PCM_CONV_DISABLE
¶
- enum
i2s_port_t
¶I2S Peripheral, 0 & 1.
Values:
I2S_NUM_0
= 0x0¶I2S 0
I2S_NUM_1
= 0x1¶I2S 1
I2S_NUM_MAX
¶
函数¶
- esp_err_t
i2s_set_pin
(i2s_port_t i2s_num, const i2s_pin_config_t *pin)¶Set I2S pin number.
Inside the pin configuration structure, set I2S_PIN_NO_CHANGE for any pin where the current configuration should not be changed.
- Note
- The I2S peripheral output signals can be connected to multiple GPIO pads. However, the I2S peripheral input signal can only be connected to one GPIO pad.
- Parameters
i2s_num
: I2S_NUM_0 or I2S_NUM_1pin
: I2S Pin structure, or NULL to set 2-channel 8-bit internal DAC pin configuration (GPIO25 & GPIO26)
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- esp_err_t
i2s_driver_install
(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size, void *i2s_queue)¶Install and start I2S driver.
This function must be called before any I2S driver read/write operations.
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1i2s_config
: I2S configurations - see i2s_config_t structqueue_size
: I2S event queue size/depth.i2s_queue
: I2S event queue handle, if set NULL, driver will not use an event queue.
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- esp_err_t
i2s_driver_uninstall
(i2s_port_t i2s_num)¶Uninstall I2S driver.
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1
- int
i2s_write_bytes
(i2s_port_t i2s_num, const char *src, size_t size, TickType_t ticks_to_wait)¶Write data to I2S DMA transmit buffer.
Format of the data in source buffer is determined by the I2S configuration (see i2s_config_t).
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1src
: Source address to write fromsize
: Size of data in bytesticks_to_wait
: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
- Return
- Number of bytes written, or ESP_FAIL (-1) for parameter error. If a timeout occurred, bytes written will be less than total size.
- int
i2s_read_bytes
(i2s_port_t i2s_num, char *dest, size_t size, TickType_t ticks_to_wait)¶Read data from I2S DMA receive buffer.
Format of the data in source buffer is determined by the I2S configuration (see i2s_config_t).
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1dest
: Destination address to read intosize
: Size of data in bytesticks_to_wait
: RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.
- Return
- Number of bytes read, or ESP_FAIL (-1) for parameter error. If a timeout occurred, bytes read will be less than total size.
- int
i2s_push_sample
(i2s_port_t i2s_num, const char *sample, TickType_t ticks_to_wait)¶Push (write) a single sample to the I2S DMA TX buffer.
Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
- Return
- Number of bytes successfully pushed to DMA buffer, or ESP_FAIL (-1) for parameter error. Will be either zero or the size of configured sample buffer.
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1sample
: Pointer to buffer containing sample to write. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.ticks_to_wait
: Push timeout in RTOS ticks. If space is not available in the DMA TX buffer within this period, no data is written and function returns 0.
- int
i2s_pop_sample
(i2s_port_t i2s_num, char *sample, TickType_t ticks_to_wait)¶Pop (read) a single sample from the I2S DMA RX buffer.
Size of the sample is determined by the channel_format (mono or stereo)) & bits_per_sample configuration (see i2s_config_t).
- Return
- Number of bytes successfully read from DMA buffer, or ESP_FAIL (-1) for parameter error. Byte count will be either zero or the size of the configured sample buffer.
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1sample
: Buffer sample data will be read into. Size of buffer (in bytes) = (number of channels) * bits_per_sample / 8.ticks_to_wait
: Pop timeout in RTOS ticks. If a sample is not available in the DMA buffer within this period, no data is read and function returns zero.
- esp_err_t
i2s_set_sample_rates
(i2s_port_t i2s_num, uint32_t rate)¶Set sample rate used for I2S RX and TX.
The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample).
bit_clock = rate * (number of channels) * bits_per_sample
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1rate
: I2S sample rate (ex: 8000, 44100…)
- esp_err_t
i2s_start
(i2s_port_t i2s_num)¶Start I2S driver.
It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop().
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1
- esp_err_t
i2s_stop
(i2s_port_t i2s_num)¶Stop I2S driver.
Disables I2S TX/RX, until i2s_start() is called.
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1
- esp_err_t
i2s_zero_dma_buffer
(i2s_port_t i2s_num)¶Zero the contents of the TX DMA buffer.
Pushes zero-byte samples into the TX DMA buffer, until it is full.
- Return
- ESP_OK Success
- ESP_FAIL Parameter error
- Parameters
i2s_num
: I2S_NUM_0, I2S_NUM_1