This document provides an overview of the ESP-BSP (Board Support Package) API as implemented by this board.
While the ESP-BSP framework defines a unified API shared across multiple boards, this documentation focuses only on the APIs supported by the current board. Any APIs not applicable to this board’s hardware are excluded or may not be functional.
The goal of this document is to make it easier for developers to understand the available APIs and how to use them consistently across different boards.
Each BSP defines a set of macros for default pin assignments used by its hardware peripherals. These macros allow users to configure or reference standard interfaces like I2C, SPI, LCD, audio, or SD cards easily.
BSP_I2C_*BSP_LCD_*BSP_I2S_*BSP_USB_*BSP_SD_*BSP_SD_SPI_*[!NOTE] Not all boards support all interfaces. You should always check if the related capability macro (e.g., BSP_CAPS_SDCARD) is defined.
Some devices included in BSPs (e.g., sensors, displays, audio codecs) communicate via the I2C interface. In many cases, I2C is initialized automatically as part of the device setup. However, you can manually initialize or deinitialize the I2C peripheral using the following API:
/* Initialize the default I2C bus used by the BSP */
bsp_i2c_init();
...
/* Deinitialize the I2C bus */
bsp_i2c_deinit();
If you need direct access to the initialized I2C bus (e.g., to communicate with an external peripheral not handled by the BSP), you can retrieve the I2C bus handle:
i2c_master_bus_handle_t i2c = bsp_i2c_get_handle();
[!NOTE] The BSP ensures that I2C initialization is performed only once, even if called multiple times. This helps avoid conflicts when multiple components rely on the same I2C bus.
Some devices included in BSPs (such as buttons, battery monitoring, etc.) use the ADC peripheral. In most cases, the ADC is automatically initialized as part of the specific device setup. However, you can manually initialize the ADC using the following API:
/* Initialize the ADC peripheral */
bsp_adc_initialize();
If you need direct access to the ADC instance (e.g., for custom measurements), you can retrieve the handle:
adc_oneshot_unit_handle_t adc = bsp_adc_get_handle();
[!NOTE] The BSP ensures the ADC is initialized only once, even if
bsp_adc_initialize()is called multiple times.
Some boards support enabling or disabling specific hardware features (such as LCD, SD card, camera, etc.) to reduce power consumption or manage shared resources. The BSP provides a unified API to control these features:
/* Enable the LCD feature */
bsp_feature_enable(BSP_FEATURE_LCD, true);
/* Disable the speaker to reduce power usage */
bsp_feature_enable(BSP_FEATURE_SPEAKER, false);
Supported feature flags (may vary depending on the board):
BSP_FEATURE_LCD - Display moduleBSP_FEATURE_TOUCH - Touch controllerBSP_FEATURE_SD - SD card interfaceBSP_FEATURE_SPEAKER-  Audio speakerBSP_FEATURE_BATTERY - Battery monitoringBSP_FEATURE_VIBRATION - Vibration motor[!NOTE] Not all BSPs support feature toggling, and some features may not be available or controllable via this API. Always check the BSP header or documentation for supported features.
[!TIP] Disabling unused features can help reduce power consumption, especially in battery-powered applications.
Each BSP defines an identifier macro in the form of BSP_BOARD_*.
| Type | Name | 
|---|---|
| define | BSP_BOARD_ESP32_S3_KORVO_1   | 
    
Each BSP defines a set of capability macros that indicate which features are supported. The list may look like this. You can use these macros to conditionally compile code depending on feature availability.
| Type | Name | 
|---|---|
| define | BSP_CAPS_AUDIO  1 | 
    
| define | BSP_CAPS_AUDIO_MIC  1 | 
    
| define | BSP_CAPS_AUDIO_SPEAKER  1 | 
    
| define | BSP_CAPS_BUTTONS  1 | 
    
| define | BSP_CAPS_DISPLAY  0 | 
    
| define | BSP_CAPS_IMU  0 | 
    
| define | BSP_CAPS_LED  1 | 
    
| define | BSP_CAPS_SDCARD  1 | 
    
| define | BSP_CAPS_TOUCH  0 | 
    
| Type | Name | 
|---|---|
| adc_oneshot_unit_handle_t | bsp_adc_get_handle (void)  Get ADC handle.  | 
    
| esp_err_t | bsp_adc_initialize (void)  Initialize ADC.  | 
    
| Type | Name | 
|---|---|
| define | BSP_ADC_UNIT  ADC_UNIT_1 | 
    
bsp_adc_get_handleGet ADC handle.
adc_oneshot_unit_handle_t bsp_adc_get_handle (
    void
) 
Note:
This function is available only in IDF5 and higher
Returns:
ADC handle
bsp_adc_initializeInitialize ADC.
esp_err_t bsp_adc_initialize (
    void
) 
The ADC can be initialized inside BSP, when needed.
| Type | Name | 
|---|---|
| esp_err_t | bsp_i2c_deinit (void)  Deinit I2C driver and free its resources.  | 
    
| i2c_master_bus_handle_t | bsp_i2c_get_handle (void)  Get I2C driver handle.  | 
    
| esp_err_t | bsp_i2c_init (void)  Init I2C driver.  | 
    
| Type | Name | 
|---|---|
| define | BSP_I2C_NUM  CONFIG_BSP_I2C_NUM | 
    
| define | BSP_I2C_SCL  (GPIO_NUM_2) | 
    
| define | BSP_I2C_SDA  (GPIO_NUM_1) | 
    
bsp_i2c_deinitDeinit I2C driver and free its resources.
esp_err_t bsp_i2c_deinit (
    void
) 
Returns:
bsp_i2c_get_handleGet I2C driver handle.
i2c_master_bus_handle_t bsp_i2c_get_handle (
    void
) 
Returns:
bsp_i2c_initInit I2C driver.
esp_err_t bsp_i2c_init (
    void
) 
Returns:
Each BSP provides a simple API for mounting and unmounting the SPI Flash File System (SPIFFS).
/* Mount SPIFFS to the virtual file system */
bsp_spiffs_mount();
/* ... perform file operations ... */
/* Unmount SPIFFS from the virtual file system */
bsp_spiffs_unmount();
The BSP offers a flexible API for working with SD cards. In addition to the default mount and unmount functions, you can also use a configuration structure or access preconfigured host and slot structures.
Mount with Default Configuration
/* Mount microSD card to the virtual file system */
bsp_sdcard_mount();
/* ... perform file operations ... */
/* Unmount microSD card */
bsp_sdcard_unmount();
Mount with Custom Configuration
Some BSPs allow selecting between SDMMC and SPI interfaces for the SD card. Use the appropriate API function based on your hardware:
bsp_sdcard_cfg_t cfg = {0};
/* Mount SD card using SDMMC interface */
bsp_sdcard_sdmmc_mount(&cfg);
or
bsp_sdcard_cfg_t cfg = {0};
/* Mount SD card using SPI interface */
bsp_sdcard_sdspi_mount(&cfg)
[!NOTE] Not all BSPs support both SDMMC and SPI modes. Check the board documentation to see which interfaces are available. If an unsupported interface is used, the API will return
ESP_ERR_NOT_SUPPORTEDerror.
Once the SD card or SPIFFS is mounted, you can use standard file I/O functions (fopen, fread, fwrite, fclose, etc.) provided by ESP-IDF’s VFS (Virtual File System).
To print basic SD card information (after mounting), you can use:
sdmmc_card_t *sdcard = bsp_sdcard_get_handle();
sdmmc_card_print_info(stdout, sdcard);
[!TIP] The bsp_sdcard_get_handle() function returns a pointer to the sdmmc_card_t structure, which contains detailed information about the connected SD card.
| Type | Name | 
|---|---|
| struct | bsp_sdcard_cfg_t  BSP SD card configuration structure.  | 
    
| Type | Name | 
|---|---|
| sdmmc_card_t * | bsp_sdcard_get_handle (void)  Get SD card handle.  | 
    
| void | bsp_sdcard_get_sdmmc_host (const int slot, sdmmc_host_t *config)  Get SD card MMC host config.  | 
    
| void | bsp_sdcard_get_sdspi_host (const int slot, sdmmc_host_t *config)  Get SD card SPI host config.  | 
    
| esp_err_t | bsp_sdcard_mount (void)  Mount microSD card to virtual file system.  | 
    
| void | bsp_sdcard_sdmmc_get_slot (const int slot, sdmmc_slot_config_t *config)  Get SD card MMC slot config.  | 
    
| esp_err_t | bsp_sdcard_sdmmc_mount (bsp_sdcard_cfg_t *cfg)  Mount microSD card to virtual file system (MMC mode)  | 
    
| void | bsp_sdcard_sdspi_get_slot (const spi_host_device_t spi_host, sdspi_device_config_t *config)  Get SD card SPI slot config.  | 
    
| esp_err_t | bsp_sdcard_sdspi_mount (bsp_sdcard_cfg_t *cfg)  Mount microSD card to virtual file system (SPI mode)  | 
    
| esp_err_t | bsp_sdcard_unmount (void)  Unmount microSD card from virtual file system.  | 
    
| esp_err_t | bsp_spiffs_mount (void)  Mount SPIFFS to virtual file system.  | 
    
| esp_err_t | bsp_spiffs_unmount (void)  Unmount SPIFFS from virtual file system.  | 
    
| Type | Name | 
|---|---|
| define | BSP_SDSPI_HOST  (SDSPI_DEFAULT_HOST) | 
    
| define | BSP_SD_CLK  (GPIO_NUM_18) | 
    
| define | BSP_SD_CMD  (GPIO_NUM_17) | 
    
| define | BSP_SD_D0  (GPIO_NUM_16) | 
    
| define | BSP_SD_D3  (GPIO_NUM_15) | 
    
| define | BSP_SD_MOUNT_POINT  CONFIG_BSP_SD_MOUNT_POINT | 
    
| define | BSP_SD_SPI_CLK  (GPIO_NUM_18) | 
    
| define | BSP_SD_SPI_CS  (GPIO_NUM_15) | 
    
| define | BSP_SD_SPI_MISO  (GPIO_NUM_16) | 
    
| define | BSP_SD_SPI_MOSI  (GPIO_NUM_17) | 
    
| define | BSP_SPIFFS_MOUNT_POINT  CONFIG_BSP_SPIFFS_MOUNT_POINT | 
    
bsp_sdcard_cfg_tBSP SD card configuration structure.
Variables:
sdmmc_host_t * host
const esp_vfs_fat_sdmmc_mount_config_t * mount
const sdmmc_slot_config_t * sdmmc
const sdspi_device_config_t * sdspi
union bsp_sdcard_cfg_t slot
bsp_sdcard_get_handleGet SD card handle.
sdmmc_card_t * bsp_sdcard_get_handle (
    void
) 
Returns:
SD card handle
bsp_sdcard_get_sdmmc_hostGet SD card MMC host config.
void bsp_sdcard_get_sdmmc_host (
    const int slot,
    sdmmc_host_t *config
) 
Parameters:
slot SD card slotconfig Structure which will be filled
    bsp_sdcard_get_sdspi_hostGet SD card SPI host config.
void bsp_sdcard_get_sdspi_host (
    const int slot,
    sdmmc_host_t *config
) 
Parameters:
slot SD card slotconfig Structure which will be filled
    bsp_sdcard_mountMount microSD card to virtual file system.
esp_err_t bsp_sdcard_mount (
    void
) 
Returns:
bsp_sdcard_sdmmc_get_slotGet SD card MMC slot config.
void bsp_sdcard_sdmmc_get_slot (
    const int slot,
    sdmmc_slot_config_t *config
) 
Parameters:
slot SD card slotconfig Structure which will be filled
    bsp_sdcard_sdmmc_mountMount microSD card to virtual file system (MMC mode)
esp_err_t bsp_sdcard_sdmmc_mount (
    bsp_sdcard_cfg_t *cfg
) 
Parameters:
cfg SD card configurationReturns:
bsp_sdcard_sdspi_get_slotGet SD card SPI slot config.
void bsp_sdcard_sdspi_get_slot (
    const spi_host_device_t spi_host,
    sdspi_device_config_t *config
) 
Parameters:
spi_host SPI host IDconfig Structure which will be filled
    bsp_sdcard_sdspi_mountMount microSD card to virtual file system (SPI mode)
esp_err_t bsp_sdcard_sdspi_mount (
    bsp_sdcard_cfg_t *cfg
) 
Parameters:
cfg SD card configurationReturns:
bsp_sdcard_unmountUnmount microSD card from virtual file system.
esp_err_t bsp_sdcard_unmount (
    void
) 
Returns:
bsp_spiffs_mountMount SPIFFS to virtual file system.
esp_err_t bsp_spiffs_mount (
    void
) 
Returns:
bsp_spiffs_unmountUnmount SPIFFS from virtual file system.
esp_err_t bsp_spiffs_unmount (
    void
) 
Returns:
Before using speaker or microphone features, the audio codec must be initialized.
/* Initialize the speaker codec */
esp_codec_dev_handle_t spk_codec_dev = bsp_audio_codec_speaker_init();
/* Initialize the microphone codec */
esp_codec_dev_handle_t mic_codec_dev = bsp_audio_codec_microphone_init();
After initialization, the esp_codec_dev API can be used to control playback and recording.
[!NOTE] Some BSPs may only support playback (speaker) or only input (microphone). Use the capability macros (
BSP_CAPS_AUDIO,BSP_CAPS_AUDIO_SPEAKER,BSP_CAPS_AUDIO_MIC) to check supported features.
Below is an example of audio playback using the speaker (source data not included):
/* Set volume to 50% */
esp_codec_dev_set_out_vol(spk_codec_dev, 50);
/* Define audio format */
esp_codec_dev_sample_info_t fs = {
    .sample_rate = wav_header.sample_rate,
    .channel = wav_header.num_channels,
    .bits_per_sample = wav_header.bits_per_sample,
};
/* Open speaker stream */
esp_codec_dev_open(spk_codec_dev, &fs);
...
/* Play audio data */
esp_codec_dev_write(spk_codec_dev, wav_bytes, wav_bytes_len);
...
/* Close stream when done */
esp_codec_dev_close(spk_codec_dev);
[!TIP] Audio data must be in raw PCM format. Use a decoder if playing compressed formats (e.g., WAV, MP3).
Below is an example of recording audio using the microphone (destination buffer not included):
/* Set input gain (optional) */
esp_codec_dev_set_in_gain(mic_codec_dev, 42.0);
/* Define audio format */
esp_codec_dev_sample_info_t fs = {
    .sample_rate = 16000,
    .channel = 1,
    .bits_per_sample = 16,
};
/* Open microphone stream */
esp_codec_dev_open(mic_codec_dev, &fs);
/* Read recorded data */
esp_codec_dev_read(mic_codec_dev, recording_buffer, BUFFER_SIZE)
...
/* Close stream when done */
esp_codec_dev_close(mic_codec_dev);
| Type | Name | 
|---|---|
| esp_codec_dev_handle_t | bsp_audio_codec_microphone_init (void)  Initialize microphone codec device.  | 
    
| esp_codec_dev_handle_t | bsp_audio_codec_speaker_init (void)  Initialize speaker codec device.  | 
    
| const audio_codec_data_if_t * | bsp_audio_get_codec_itf_mic (void)  Get es7210 codec I2S interface (initialized in bsp_audio_init)  | 
    
| const audio_codec_data_if_t * | bsp_audio_get_codec_itf_spk (void)  Get es8311 codec I2S interface (initialized in bsp_audio_init)  | 
    
| esp_err_t | bsp_audio_init (const i2s_std_config_t *i2s_config)  Init audio.  | 
    
| Type | Name | 
|---|---|
| define | BSP_I2S0_DOUT  (GPIO_NUM_39) | 
    
| define | BSP_I2S0_DSIN  (GPIO_NUM_NC) | 
    
| define | BSP_I2S0_LCLK  (GPIO_NUM_41) | 
    
| define | BSP_I2S0_MCLK  (GPIO_NUM_42) | 
    
| define | BSP_I2S0_SCLK  (GPIO_NUM_40) | 
    
| define | BSP_I2S1_DOUT  (GPIO_NUM_NC) | 
    
| define | BSP_I2S1_DSIN  (GPIO_NUM_11) | 
    
| define | BSP_I2S1_LCLK  (GPIO_NUM_9) | 
    
| define | BSP_I2S1_MCLK  (GPIO_NUM_20) | 
    
| define | BSP_I2S1_SCLK  (GPIO_NUM_10) | 
    
| define | BSP_POWER_AMP_IO  (GPIO_NUM_38) | 
    
bsp_audio_codec_microphone_initInitialize microphone codec device.
esp_codec_dev_handle_t bsp_audio_codec_microphone_init (
    void
) 
Returns:
Pointer to codec device handle or NULL when error occurred
bsp_audio_codec_speaker_initInitialize speaker codec device.
esp_codec_dev_handle_t bsp_audio_codec_speaker_init (
    void
) 
Returns:
Pointer to codec device handle or NULL when error occurred
bsp_audio_get_codec_itf_micGet es7210 codec I2S interface (initialized in bsp_audio_init)
const audio_codec_data_if_t * bsp_audio_get_codec_itf_mic (
    void
) 
Returns:
bsp_audio_get_codec_itf_spkGet es8311 codec I2S interface (initialized in bsp_audio_init)
const audio_codec_data_if_t * bsp_audio_get_codec_itf_spk (
    void
) 
Returns:
bsp_audio_initInit audio.
esp_err_t bsp_audio_init (
    const i2s_std_config_t *i2s_config
) 
Note:
There is no deinit audio function. Users can free audio resources by calling i2s_del_channel()
Warning:
The type of i2s_config param is depending on IDF version.
Parameters:
i2s_config I2S configuration. Pass NULL to use default values (Mono, duplex, 16bit, 22050 Hz)Returns:
Most boards include one or more user buttons. The BSP provides a simple API to initialize and use them. Internally, it utilizes the button component for event handling and debouncing.
/* Initialize all available buttons */
button_handle_t btns[BSP_BUTTON_NUM] = {NULL};
bsp_iot_button_create(btns, NULL, BSP_BUTTON_NUM);
/* Register a callback for button press */
for (int i = 0; i < BSP_BUTTON_NUM; i++) {
    iot_button_register_cb(btns[i], BUTTON_PRESS_DOWN, NULL, btn_handler, (void *) i);
}
/* Called on button press */
static void btn_handler(void *button_handle, void *usr_data)
{
    int button_index = (int)usr_data;
    ESP_LOGI(TAG, "Button %d pressed", button_index);
}
Notes:
BSP_BUTTON_NUM defines the number of available buttons on the board
Instead of relying on a numeric index, you can use the bsp_button_t structure defined in the BSP header to reference buttons by name (e.g., BSP_BUTTON_MUTE, BSP_BUTTON_MAIN, BSP_BUTTON_BOOT, etc.)
The callback can be registered for different button events, such as BUTTON_PRESS_DOWN, BUTTON_PRESS_UP, or BUTTON_LONG_PRESS_START, BUTTON_DOUBLE_CLICK, …
Button features (e.g. long-press support, active level) are configured automatically by the BSP.
| Type | Name | 
|---|---|
| enum | bsp_button_t   | 
    
| Type | Name | 
|---|---|
| esp_err_t | bsp_iot_button_create (button_handle_t btn_array, int *btn_cnt, int btn_array_size)  Initialize all buttons.  | 
    
| Type | Name | 
|---|---|
| define | BSP_BUTTONS_IO  (GPIO_NUM_8) | 
    
bsp_button_tenum bsp_button_t {
    BSP_BUTTON_REC = 0,
    BSP_BUTTON_MODE,
    BSP_BUTTON_PLAY,
    BSP_BUTTON_SET,
    BSP_BUTTON_VOLDOWN,
    BSP_BUTTON_VOLUP,
    BSP_BUTTON_NUM
};
bsp_iot_button_createInitialize all buttons.
esp_err_t bsp_iot_button_create (
    button_handle_t btn_array,
    int *btn_cnt,
    int btn_array_size
) 
Returned button handlers must be used with espressif/button component API
Parameters:
btn_array Output button arraybtn_cnt Number of button handlers saved to btn_array, can be NULLbtn_array_size Size of output button array. Must be at least BSP_BUTTON_NUMReturns:
LEDs are handled similarly to buttons in BSP. The BSP uses the led_indicator component, which provides simple control over LED states and built-in effects such as blinking, breathing, and more. It also supports addressable RGB LEDs.
/* Initialize all LEDs */
bsp_led_indicator_create(leds, NULL, BSP_LED_NUM);
/* Set color of the first LED (for addressable RGB LEDs only) */
led_indicator_set_rgb(leds[0], SET_IRGB(0, 0x00, 0x64, 0x64));
/*
Start a predefined LED effect:
- BSP_LED_ON
- BSP_LED_OFF
- BSP_LED_BLINK_FAST
- BSP_LED_BLINK_SLOW
- BSP_LED_BREATHE_FAST
- BSP_LED_BREATHE_SLOW
*/
led_indicator_start(leds[0], BSP_LED_BREATHE_SLOW);
Notes:
BSP_LED_NUM defines the total number of available LEDs on the board| Type | Name | 
|---|---|
| enum | bsp_led_effect_t   | 
    
| Type | Name | 
|---|---|
| esp_err_t | bsp_led_indicator_create (led_indicator_handle_t led_array, int *led_cnt, int led_array_size)  Initialize all LEDs.  | 
    
| Type | Name | 
|---|---|
| define | BSP_LED_NUM  (12) | 
    
| define | BSP_LED_RGB_GPIO  (GPIO_NUM_19) | 
    
bsp_led_effect_tenum bsp_led_effect_t {
    BSP_LED_ON,
    BSP_LED_OFF,
    BSP_LED_BLINK_FAST,
    BSP_LED_BLINK_SLOW,
    BSP_LED_BREATHE_FAST,
    BSP_LED_BREATHE_SLOW,
    BSP_LED_MAX
};
bsp_led_indicator_createInitialize all LEDs.
esp_err_t bsp_led_indicator_create (
    led_indicator_handle_t led_array,
    int *led_cnt,
    int led_array_size
) 
Note:
led_cnt and led_array_size unused, only one config needed to control the leds
Parameters:
led_array Output LED arrayled_cnt Number of LED handlers saved to led_array, can be NULLled_array_size Size of output LED array. Must be at least BSP_LED_NUMReturns: