Inter-IC Sound (I²S) API Reference#

The Inter-IC Sound (I²S) application programming interface (API) for SiWx917 devices (Si91x family) in the WiSeConnect software development kit (SDK) provides the modules, data types, configuration structures, functions, and macros required to configure and use I²S peripherals.

These APIs allow applications to operate in primary (controller) or secondary (target) roles, define audio formats, sample rates, and channel configurations, and perform audio transfers using blocking, interrupt-driven, or direct memory access (DMA)–assisted methods.

Public APIs#

This section introduces the public I²S APIs available on the SiWx917 platform. It covers the API surface (including modules, enumerations, configuration structures, functions, and macros) and provides short examples for common operations.

With these APIs, you can:

• Configure I²S as primary (controller) or secondary (target)

• Select audio formats (16-bit, 24-bit, and 32-bit) and sample rate

• Manage audio transfers using blocking, interrupt, or DMA-assisted methods

• Receive event callbacks for transfer completion and error handling

Complete reference:
I²S Public APIs — WiSeConnect (Si91x)

Callback and Notification APIs#

In addition to synchronous (blocking) calls, the I²S driver supports asynchronous callbacks for event notifications. By registering a callback function (usually during initialization), your application can respond to transfer completion, underruns, or errors without polling.

Callback Function Definition#

typedef void (*sl_i2s_callback_t)(sl_i2s_instance_t i2s_instance, uint32_t event);

Parameters#

• i2s_instance: Identifies the I²S instance that generated the event.

• event: Provides an event code indicating the type of event (for example, transmit complete, underrun, or error).

Usage Guidelines#

Register the callback during initialization or through the driver’s callback registration API. When an event occurs, the driver invokes the callback so the application can respond appropriately (for example, marking a buffer as complete or initiating recovery).

Keep the callback non-blocking and defer complex processing to a task/thread.

Steps#

1. Implement a callback that matches sl_i2s_callback_t.

2. Assign it to your I²S configuration structure (config.i2s_callback = my_i2s_event_cb;).

3. Call sl_i2s_driver_init() with the instance and configuration.

Example#

void my_i2s_event_handler(sl_i2s_instance_t i2s_instance, uint32_t event) {
    if (event == SL_I2S_EVENT_TX_COMPLETE) {
        // Handle successful transmission
    } else if (event == SL_I2S_EVENT_ERROR) {
        // Handle error condition
    }
}

void app_i2s_init(void)
{
    sl_i2s_config_t config = {0};
    // Configure role, format, sample rate, and pins
    config.i2s_callback = my_i2s_event_handler;  // attach your callback

    sl_i2s_driver_init(SL_I2S_INSTANCE_0, &config);  // initialize driver
}

Integration#

Callbacks improve efficiency by eliminating polling. Decode the event in the handler, update your application state, and schedule further operations in a separate thread or deferred routine.

Example Projects#

The WiSeConnect SDK includes ready-to-use example projects that demonstrate common I²S use cases:

• I²S Primary Example

• I²S Secondary Example

• I²S Loopback

• Ultra-Low Power (ULP) I²S Example

These examples demonstrate typical use cases, primary and secondary configurations, DMA-based transfers, and low-power audio streaming.