| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
I2S
This information applies to the nRF52 Series only.

The Inter-IC Sound (I2S) interface driver includes two layers: the hardware access layer (HAL) and the driver layer (DRV).

The hardware access layer provides basic APIs for accessing the registers of the I2S peripheral. See the API documentation for the I2S HAL for details.

The driver layer provides APIs on a higher level than the HAL. See the API documentation for the I2S driver for details.

Key features include:

- Three modes of operation:
  - Reception (RX) only
  - Transmission (TX) only
  - Both directions simultaneously
- Data exchange through a single data handler that is called by the driver when new data is received or new data is needed for transmission

The I2S Loopback Example provides sample code that you can use to quickly get started.

# Driver configuration

The configurable parameters include:

- Pins to be used for I2S peripheral signals
- Operating mode (master or slave)
- Format of frames, used channels (stereo, left or right)
- Width and alignment of samples
- Clock settings (defining the sampling frequency in master mode)

The default configuration for the I2S driver is located in `sdk_config.h`. This configuration is used when nrf_drv_i2s_init is called with a NULL pointer to the configuration structure.

The driver must be explicitly enabled in `sdk_config.h` before it can be used. A proper data handling function must be provided during the initialization.

# Using the I2S driver

First, define the data handling function for I2S transfers. For example:

static void data_handler(uint32_t const * p_data_received,
uint32_t * p_data_to_send,
uint16_t number_of_words)
{
if (p_data_received != NULL)
{
// Process the received data.
}
if (p_data_to_send != NULL)
{
// Provide the data to be sent.
}
}

Next, call nrf_drv_i2s_init to initialize and configure the instance. See the nrf_drv_i2s_config_t structure documentation for possible configuration options.

For example:

uint32_t err_code;
nrf_drv_i2s_config_t config = NRF_DRV_I2S_DEFAULT_CONFIG;
config.mck_setup = NRF_I2S_MCK_32MDIV21;
config.ratio = NRF_I2S_RATIO_96X;
err_code = nrf_drv_i2s_init(&config, data_handler);
if (err_code != NRF_SUCCESS)
{
// Initialization failed. Take recovery action.
}

Start the transfer by calling nrf_drv_i2s_start and providing a proper buffer for a given direction if it should be enabled. See the following examples:

- RX only:
  nrf_drv_i2s_start(m_buffer_rx, NULL, I2S_BUFFER_SIZE, 0);
- TX only:
  nrf_drv_i2s_start(NULL, m_buffer_tx, I2S_BUFFER_SIZE, 0);
- Both directions:
  nrf_drv_i2s_start(m_buffer_rx, m_buffer_tx, I2S_BUFFER_SIZE, 0);

If both RX and TX are enabled, you can use the NRF_DRV_I2S_FLAG_SYNCHRONIZED_MODE flag to force a common call to the data handler for RX and TX data. Normally, the driver calls the data handler as soon as the event for a given direction is generated by the I2S peripheral. In synchronized mode, the call is deferred until events for both directions occur. This mode is useful, for example, when received data should be processed and then transmitted.

At any time, the transfer can be stopped immediately by calling nrf_drv_i2s_stop.

When the I2S driver is no longer needed or its configuration must be changed, call nrf_drv_i2s_uninit.