esp-bsp

API Reference

| :1234: [CAPABILITIES](#1234-capabilities) | :floppy_disk: [SD CARD AND SPIFFS](#floppy_disk-sd-card-and-spiffs) | :musical_note: [AUDIO](#musical_note-audio) | :pager: [DISPLAY AND TOUCH](#pager-display-and-touch) | :radio_button: [BUTTONS](#radio_button-buttons) | :bulb: [LEDS](#bulb-leds) | :camera: [CAMERA](#camera-camera) | :battery: [BATTERY](#battery-battery) | | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: | :-------------------------: |

Overview

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.

General

Pinout

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.

I2C: BSP_I2C_*
Display: BSP_LCD_*
Audio I2S: BSP_I2S_*
USB: BSP_USB_*
SD Card (MMC): BSP_SD_*
SD Card (SPI): 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.

I2C

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.

ADC

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.

Features

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 module
BSP_FEATURE_TOUCH - Touch controller
BSP_FEATURE_SD - SD card interface
BSP_FEATURE_SPEAKER- Audio speaker
BSP_FEATURE_BATTERY - Battery monitoring
BSP_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.

Identification

Each BSP defines an identifier macro in the form of BSP_BOARD_*.

Board Name API Reference

Macros

Type	Name
define	BSP_BOARD_ESP32_P4_EYE

:1234: Capabilities

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.

Capabilities API Reference

Macros

Type	Name
define	BSP_CAPS_AUDIO 1
define	BSP_CAPS_AUDIO_MIC 1
define	BSP_CAPS_AUDIO_SPEAKER 0
define	BSP_CAPS_BAT 1
define	BSP_CAPS_BUTTONS 1
define	BSP_CAPS_CAMERA 1
define	BSP_CAPS_DISPLAY 1
define	BSP_CAPS_IMU 0
define	BSP_CAPS_KNOB 1
define	BSP_CAPS_LED 1
define	BSP_CAPS_SDCARD 1
define	BSP_CAPS_TOUCH 0

ADC API Reference

Functions

Type	Name
adc_oneshot_unit_handle_t	bsp_adc_get_handle (void) Get ADC handle.
esp_err_t	bsp_adc_initialize (void) Initialize ADC.

Macros

Type	Name
define	BSP_ADC_UNIT ADC_UNIT_2

Functions Documentation

function `bsp_adc_get_handle`

Get 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

function `bsp_adc_initialize`

Initialize ADC.

esp_err_t bsp_adc_initialize (
    void
) 

The ADC can be initialized inside BSP, when needed.

I2C API Reference

Functions

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.

Macros

Type	Name
define	BSP_I2C_NUM CONFIG_BSP_I2C_NUM
define	BSP_I2C_SCL (GPIO_NUM_13)
define	BSP_I2C_SDA (GPIO_NUM_14)

Functions Documentation

function `bsp_i2c_deinit`

Deinit I2C driver and free its resources.

esp_err_t bsp_i2c_deinit (
    void
) 

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG I2C parameter error
function bsp_i2c_get_handle

Get I2C driver handle.

i2c_master_bus_handle_t bsp_i2c_get_handle (
    void
) 

Returns:

I2C handle
function bsp_i2c_init

Init I2C driver.

esp_err_t bsp_i2c_init (
    void
) 

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG I2C parameter error
ESP_FAIL I2C driver installation error

:floppy_disk: SD Card and SPIFFS

SPIFFS Initialization / Deinitialization

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();

SD Card Initialization / Deinitialization

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);

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_SUPPORTED error.

After Mounting

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.

SD Card and SPIFFS API Reference

Structures and Types

Type	Name
struct	bsp_sdcard_cfg_t BSP SD card configuration structure.

Functions

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 micorSD 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.

Macros

Type	Name
define	BSP_SDSPI_HOST (SPI3_HOST)
define	BSP_SD_CLK (GPIO_NUM_43)
define	BSP_SD_CMD (GPIO_NUM_44)
define	BSP_SD_D0 (GPIO_NUM_39)
define	BSP_SD_D1 (GPIO_NUM_40)
define	BSP_SD_D2 (GPIO_NUM_41)
define	BSP_SD_D3 (GPIO_NUM_42)
define	BSP_SD_DET (GPIO_NUM_45)
define	BSP_SD_EN (GPIO_NUM_46)
define	BSP_SD_MOUNT_POINT CONFIG_BSP_SD_MOUNT_POINT
define	BSP_SD_SPI_CLK (GPIO_NUM_43)
define	BSP_SD_SPI_CS (GPIO_NUM_42)
define	BSP_SD_SPI_MISO (GPIO_NUM_39)
define	BSP_SD_SPI_MOSI (GPIO_NUM_44)
define	BSP_SPIFFS_MOUNT_POINT CONFIG_BSP_SPIFFS_MOUNT_POINT

Structures and Types Documentation

struct `bsp_sdcard_cfg_t`

BSP 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

Functions Documentation

function `bsp_sdcard_get_handle`

Get SD card handle.

sdmmc_card_t * bsp_sdcard_get_handle (
    void
) 

Returns:

SD card handle

function `bsp_sdcard_get_sdmmc_host`

Get SD card MMC host config.

void bsp_sdcard_get_sdmmc_host (
    const int slot,
    sdmmc_host_t *config
) 

Parameters:

slot SD card slot
config Structure which will be filled
function bsp_sdcard_get_sdspi_host

Get SD card SPI host config.

void bsp_sdcard_get_sdspi_host (
    const int slot,
    sdmmc_host_t *config
) 

Parameters:

slot SD card slot
config Structure which will be filled
function bsp_sdcard_mount

Mount microSD card to virtual file system.

esp_err_t bsp_sdcard_mount (
    void
) 

Returns:

ESP_OK on success
ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
ESP_ERR_NO_MEM if memory can not be allocated
ESP_FAIL if partition can not be mounted
other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
function bsp_sdcard_sdmmc_get_slot

Get SD card MMC slot config.

void bsp_sdcard_sdmmc_get_slot (
    const int slot,
    sdmmc_slot_config_t *config
) 

Parameters:

slot SD card slot
config Structure which will be filled
function bsp_sdcard_sdmmc_mount

Mount microSD card to virtual file system (MMC mode)

esp_err_t bsp_sdcard_sdmmc_mount (
    bsp_sdcard_cfg_t *cfg
) 

Parameters:

cfg SD card configuration

Returns:

ESP_OK on success
ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
ESP_ERR_NO_MEM if memory cannot be allocated
ESP_FAIL if partition cannot be mounted
other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
function bsp_sdcard_sdspi_get_slot

Get 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 ID
config Structure which will be filled
function bsp_sdcard_sdspi_mount

Mount microSD card to virtual file system (SPI mode)

esp_err_t bsp_sdcard_sdspi_mount (
    bsp_sdcard_cfg_t *cfg
) 

Parameters:

cfg SD card configuration

Returns:

ESP_OK on success
ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
ESP_ERR_NO_MEM if memory cannot be allocated
ESP_FAIL if partition cannot be mounted
other error codes from SDMMC or SPI drivers, SDMMC protocol, or FATFS drivers
function bsp_sdcard_unmount

Unmount micorSD card from virtual file system.

esp_err_t bsp_sdcard_unmount (
    void
) 

Returns:

ESP_OK on success
ESP_ERR_NOT_FOUND if the partition table does not contain FATFS partition with given label
ESP_ERR_INVALID_STATE if esp_vfs_fat_spiflash_mount was already called
ESP_ERR_NO_MEM if memory can not be allocated
ESP_FAIL if partition can not be mounted
other error codes from wear levelling library, SPI flash driver, or FATFS drivers
function bsp_spiffs_mount

Mount SPIFFS to virtual file system.

esp_err_t bsp_spiffs_mount (
    void
) 

Returns:

ESP_OK on success
ESP_ERR_INVALID_STATE if esp_vfs_spiffs_register was already called
ESP_ERR_NO_MEM if memory can not be allocated
ESP_FAIL if partition can not be mounted
other error codes
function bsp_spiffs_unmount

Unmount SPIFFS from virtual file system.

esp_err_t bsp_spiffs_unmount (
    void
) 

Returns:

ESP_OK on success
ESP_ERR_NOT_FOUND if the partition table does not contain SPIFFS partition with given label
ESP_ERR_INVALID_STATE if esp_vfs_spiffs_unregister was already called
ESP_ERR_NO_MEM if memory can not be allocated
ESP_FAIL if partition can not be mounted
other error codes

:musical_note: Audio

Initialization

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.

Example of audio usage

Speaker

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).

Microphone

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);

Audio API Reference

Functions

Type	Name
esp_codec_dev_handle_t	bsp_audio_codec_microphone_init (void) Initialize microphone codec device.
const audio_codec_data_if_t *	bsp_audio_get_codec_itf (void) Get codec I2S interface (initialized in bsp_audio_init)
esp_err_t	bsp_audio_init (const i2s_std_config_t i2s_config) Init audio.*

Macros

Type	Name
define	BSP_I2S_CLK (GPIO_NUM_22)
define	BSP_I2S_DOUT (GPIO_NUM_NC)
define	BSP_I2S_DSIN (GPIO_NUM_21)

Functions Documentation

function `bsp_audio_codec_microphone_init`

Initialize 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

function `bsp_audio_get_codec_itf`

Get codec I2S interface (initialized in bsp_audio_init)

const audio_codec_data_if_t * bsp_audio_get_codec_itf (
    void
) 

Returns:

Pointer to codec I2S interface handle or NULL when error occurred
function bsp_audio_init

Init 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()

Parameters:

i2s_config I2S configuration. Pass NULL to use default values

Returns:

ESP_OK On success
ESP_ERR_NOT_SUPPORTED The communication mode is not supported on the current chip
ESP_ERR_INVALID_ARG NULL pointer or invalid configuration
ESP_ERR_NOT_FOUND No available I2S channel found
ESP_ERR_NO_MEM No memory for storing the channel information
ESP_ERR_INVALID_STATE This channel has not initialized or already started

Initialization

ESP-BSP provides two ways to initialize the display, touch and LVGL.

Simple method:

/* Initialize display, touch, and LVGL */
lv_display_t display = bsp_display_start();

Configurable method:

bsp_display_cfg_t cfg = {
    .lvgl_port_cfg = ESP_LVGL_PORT_INIT_CONFIG(),   /* See LVGL Port for more info */
    .buffer_size = BSP_LCD_V_RES * BSP_LCD_H_RES,   /* Screen buffer size in pixels */
    .double_buffer = true,                          /* Allocate two buffers if true */
    .flags = {
        .buff_dma = true,                           /* Use DMA-capable LVGL buffer */
        .buff_spiram = false,                       /* Allocate buffer in PSRAM if true */
    }
};
cfg.lvgl_port_cfg.task_stack = 10000;   /* Example: change LVGL task stack size */
/* Initialize display, touch, and LVGL */
lv_display_t display = bsp_display_start_with_config(&cfg);

After initialization, you can use the LVGL API or LVGL Port API.

Initialization without LVGL - NoGLIB BSP

To initialize the LCD without LVGL, use:

esp_lcd_panel_handle_t panel_handle;
esp_lcd_panel_io_handle_t io_handle;
const bsp_display_config_t bsp_disp_cfg = {
    .max_transfer_sz = (BSP_LCD_H_RES * 100) * sizeof(uint16_t),
};
BSP_ERROR_CHECK_RETURN_NULL(bsp_display_new(&bsp_disp_cfg, &panel_handle, &io_handle));

To initialize the LCD touch without LVGL, use:

esp_lcd_touch_handle_t tp;
bsp_touch_new(NULL, &tp);

After initialization, you can use the ESP-LCD API and ESP-LCD Touch API.

Set Brightness

/* Set display brightness to 100% */
bsp_display_backlight_on();

/* Set display brightness to 0% */
bsp_display_backlight_off();

/* Set display brightness to 50% */
bsp_display_brightness_set(50);

[!NOTE] Some boards do not support changing brightness. They return an ESP_ERR_NOT_SUPPORTED error.

LVGL API Usage (only when initialized with LVGL)

All LVGL calls must be protected using lock/unlock:

/* Wait until other tasks finish screen operations */
bsp_display_lock(0);
...
lv_obj_t * screen = lv_disp_get_scr_act(disp_handle);
lv_obj_t * obj = lv_label_create(screen);
...
/* Unlock after screen operations are done */
bsp_display_unlock();

Screen rotation (only when initialized with LVGL)

bsp_display_lock(0);
/* Rotate display to 90 */
bsp_display_rotate(display, LV_DISPLAY_ROTATION_90);
bsp_display_unlock();

[!NOTE] Some LCDs do not support hardware rotation and instead use software rotation, which consumes more memory.

Available constants

Constants like screen resolution, pin configuration, and other options are defined in the BSP header files ({bsp_name}.h, display.h, touch.h). Below are some of the most relevant predefined constants:

BSP_LCD_H_RES - Horizontal resolution in pixels
BSP_LCD_V_RES - Vertical resolution in pixels
BSP_LCD_SPI_NUM - SPI bus used by the LCD (if applicable)

Display and Touch API Reference

Structures and Types

Type	Name
struct	bsp_display_cfg_t BSP display configuration structure.
struct	bsp_display_config_t BSP display configuration structure.

Functions

Type	Name
esp_err_t	bsp_display_backlight_off (void) Turn off display backlight.
esp_err_t	bsp_display_backlight_on (void) Turn on display backlight.
esp_err_t	bsp_display_brightness_init (void) Initialize display’s brightness.
esp_err_t	bsp_display_brightness_set (int brightness_percent) Set display’s brightness.
esp_err_t	bsp_display_enter_sleep (void) Set display enter sleep mode.
esp_err_t	bsp_display_exit_sleep (void) Set display exit sleep mode.
lv_indev_t *	bsp_display_get_input_dev (void) Get pointer to input device (touch, buttons, …)
bool	bsp_display_lock (uint32_t timeout_ms) Take LVGL mutex.
esp_err_t	bsp_display_new (const bsp_display_config_t config, esp_lcd_panel_handle_t ret_panel, esp_lcd_panel_io_handle_t ret_io) Create new display panel.*
void	bsp_display_rotate (lv_display_t disp, lv_disp_rotation_t rotation) Rotate screen.*
lv_display_t *	bsp_display_start (void) Initialize display.
lv_display_t *	bsp_display_start_with_config (const bsp_display_cfg_t cfg) Initialize display.*
void	bsp_display_unlock (void) Give LVGL mutex.

Macros

Type	Name
define	BSP_LCD_BACKLIGHT (GPIO_NUM_20)
define	BSP_LCD_BIGENDIAN (1)
define	BSP_LCD_BITS_PER_PIXEL (16)
define	BSP_LCD_COLOR_FORMAT (ESP_LCD_COLOR_FORMAT_RGB565)
define	BSP_LCD_COLOR_SPACE (LCD_RGB_ELEMENT_ORDER_RGB)
define	BSP_LCD_CS (GPIO_NUM_18)
define	BSP_LCD_DATA0 (GPIO_NUM_16)
define	BSP_LCD_DC (GPIO_NUM_19)
define	BSP_LCD_EN (GPIO_NUM_12)
define	BSP_LCD_H_RES (240)
define	BSP_LCD_PCLK (GPIO_NUM_17)
define	BSP_LCD_PIXEL_CLOCK_HZ (80 * 1000 * 1000)
define	BSP_LCD_RST (GPIO_NUM_15)
define	BSP_LCD_SPI_NUM (SPI2_HOST)
define	BSP_LCD_V_RES (240)
define	ESP_LCD_COLOR_FORMAT_RGB565 (1)
define	ESP_LCD_COLOR_FORMAT_RGB888 (2)

Structures and Types Documentation

struct `bsp_display_cfg_t`

BSP display configuration structure.

Variables:

unsigned int buff_dma
Allocated LVGL buffer will be DMA capable
unsigned int buff_spiram
Allocated LVGL buffer will be in PSRAM
uint32_t buffer_size
Size of the buffer for the screen in pixels
bool double_buffer
True, if should be allocated two buffers
struct bsp_display_cfg_t flags
lvgl_port_cfg_t lvgl_port_cfg
LVGL port configuration

struct `bsp_display_config_t`

BSP display configuration structure.

Variables:

int max_transfer_sz
Maximum transfer size, in bytes.

Functions Documentation

function `bsp_display_backlight_off`

Turn off display backlight.

esp_err_t bsp_display_backlight_off (
    void
) 

Brightness is controlled with PWM signal to a pin controlling backlight. Brightness must be already initialized by calling bsp_display_brightness_init() orbsp_display_new()

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG Parameter error
function bsp_display_backlight_on

Turn on display backlight.

esp_err_t bsp_display_backlight_on (
    void
) 

Brightness is controlled with PWM signal to a pin controlling backlight. Brightness must be already initialized by calling bsp_display_brightness_init() orbsp_display_new()

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG Parameter error
function bsp_display_brightness_init

Initialize display’s brightness.

esp_err_t bsp_display_brightness_init (
    void
) 

Brightness is controlled with PWM signal to a pin controlling backlight.

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG Parameter error
function bsp_display_brightness_set

Set display’s brightness.

esp_err_t bsp_display_brightness_set (
    int brightness_percent
) 

Brightness is controlled with PWM signal to a pin controlling backlight. Brightness must be already initialized by calling bsp_display_brightness_init() orbsp_display_new()

Parameters:

brightness_percent Brightness in [%]

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG Parameter error
function bsp_display_enter_sleep

Set display enter sleep mode.

esp_err_t bsp_display_enter_sleep (
    void
) 

All the display (LCD, backlight, touch) will enter sleep mode.

Returns:

ESP_OK on success
ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel
function bsp_display_exit_sleep

Set display exit sleep mode.

esp_err_t bsp_display_exit_sleep (
    void
) 

All the display (LCD, backlight, touch) will exit sleep mode.

Returns:

ESP_OK on success
ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel
function bsp_display_get_input_dev

Get pointer to input device (touch, buttons, …)

lv_indev_t * bsp_display_get_input_dev (
    void
) 

Note:

The LVGL input device is initialized in bsp_display_start() function.

Returns:

Pointer to LVGL input device or NULL when not initialized

function `bsp_display_lock`

Take LVGL mutex.

bool bsp_display_lock (
    uint32_t timeout_ms
) 

Parameters:

timeout_ms Timeout in [ms]. 0 will block indefinitely.

Returns:

true Mutex was taken

Returns:

false Mutex was NOT taken

function `bsp_display_new`

Create new display panel.

esp_err_t bsp_display_new (
    const bsp_display_config_t *config,
    esp_lcd_panel_handle_t *ret_panel,
    esp_lcd_panel_io_handle_t *ret_io
) 

For maximum flexibility, this function performs only reset and initialization of the display. You must turn on the display explicitly by calling esp_lcd_panel_disp_on_off(). The display’s backlight is not turned on either. You can use bsp_display_backlight_on/off(), bsp_display_brightness_set() (on supported boards) or implement your own backlight control.

If you want to free resources allocated by this function, you can use esp_lcd API, ie.:

esp_lcd_panel_del(panel);
esp_lcd_panel_io_del(io);
spi_bus_free(spi_num_from_configuration);

Parameters:

config display configuration
ret_panel esp_lcd panel handle
ret_io esp_lcd IO handle

Returns:

ESP_OK On success
Else esp_lcd failure
function bsp_display_rotate

Rotate screen.

void bsp_display_rotate (
    lv_display_t *disp,
    lv_disp_rotation_t rotation
) 

Display must be already initialized by calling bsp_display_start()

Parameters:

disp Pointer to LVGL display
rotation Angle of the display rotation
function bsp_display_start

Initialize display.

lv_display_t * bsp_display_start (
    void
) 

This function initializes SPI, display controller and starts LVGL handling task. LCD backlight must be enabled separately by calling bsp_display_brightness_set()

Returns:

Pointer to LVGL display or NULL when error occurred

function `bsp_display_start_with_config`

Initialize display.

lv_display_t * bsp_display_start_with_config (
    const bsp_display_cfg_t *cfg
) 

This function initializes SPI, display controller and starts LVGL handling task. LCD backlight must be enabled separately by calling bsp_display_brightness_set()

Parameters:

cfg display configuration

Returns:

Pointer to LVGL display or NULL when error occurred

function `bsp_display_unlock`

Give LVGL mutex.

void bsp_display_unlock (
    void
) 

:radio_button: Buttons

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.

Buttons API Reference

Structures and Types

Type	Name
enum	bsp_button_t

Functions

Type	Name
esp_err_t	bsp_iot_button_create (button_handle_t btn_array, int btn_cnt, int btn_array_size) Initialize all buttons.*

Macros

Type	Name
define	BSP_BUTTON_1_IO (GPIO_NUM_35)

Structures and Types Documentation

enum `bsp_button_t`

enum bsp_button_t {
    BSP_BUTTON_1,
    BSP_BUTTON_NUM
};

Functions Documentation

function `bsp_iot_button_create`

Initialize 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 array
btn_cnt Number of button handlers saved to btn_array, can be NULL
btn_array_size Size of output button array. Must be at least BSP_BUTTON_NUM

Returns:

ESP_OK All buttons initialized
ESP_ERR_INVALID_ARG btn_array is too small or NULL
ESP_FAIL Underlaying iot_button_create failed

:bulb: LEDs

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
LEDs are automatically configured by the BSP (no need to set GPIO or direction manually)

Leds API Reference

Structures and Types

Type	Name
enum	bsp_led_effect_t
enum	bsp_led_t

Functions

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.*
esp_err_t	bsp_led_set (led_indicator_handle_t handle, const bool on) Turn LED on/off.

Macros

Type	Name
define	BSP_LED_1_IO (GPIO_NUM_23)

Structures and Types Documentation

enum `bsp_led_effect_t`

enum 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
};

enum `bsp_led_t`

enum bsp_led_t {
    BSP_LED_1,
    BSP_LED_NUM
};

Functions Documentation

function `bsp_led_indicator_create`

Initialize all LEDs.

esp_err_t bsp_led_indicator_create (
    led_indicator_handle_t led_array,
    int *led_cnt,
    int led_array_size
) 

Parameters:

led_array Output LED array
led_cnt Number of LED handlers saved to led_array, can be NULL
led_array_size Size of output LED array. Must be at least BSP_LED_NUM

Returns:

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error
function bsp_led_set

Turn LED on/off.

esp_err_t bsp_led_set (
    led_indicator_handle_t handle,
    const bool on
) 

Parameters:

handle led handle
on Switch LED on/off

Returns:

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

:camera: Camera

There is no dedicated BSP API for camera functionality. Instead, the BSP provides default configuration macros:

BSP_CAMERA_DEFAULT_CONFIG
BSP_CAMERA_VFLIP
BSP_CAMERA_HMIRROR

These macros are designed for use with the esp32-camera component.

[!NOTE] Don’t forget to initialize I2C (bsp_i2c_init()) before using the camera, as some camera modules require I2C for configuration.

Example Usage

/* Initialize I2C bus (required by camera module) */
bsp_i2c_init();

/* Initialize the camera using BSP default config */
const camera_config_t camera_config = BSP_CAMERA_DEFAULT_CONFIG;
esp_camera_init(&camera_config);

/* Optional: Set camera orientation */
sensor_t *s = esp_camera_sensor_get();
s->set_vflip(s, BSP_CAMERA_VFLIP);     // Vertical flip
s->set_hmirror(s, BSP_CAMERA_HMIRROR); // Horizontal mirror

...

/* Capture a frame */
camera_fb_t * pic = esp_camera_fb_get();
if (pic) {
    /* Access raw image data in pic->buf with size pic->len */
    process_image(pic->buf, pic->len);  // Replace with your function
    esp_camera_fb_return(pic);
}

Camera API Reference

Functions

Type	Name
esp_err_t	bsp_camera_start (void) Initialize camera.

Macros

Type	Name
define	BSP_CAMERA_EN (GPIO_NUM_12)
define	BSP_CAMERA_GPIO_XCLK (GPIO_NUM_11)
define	BSP_CAMERA_RST (GPIO_NUM_26)
define	BSP_CAMERA_XCLK_CLOCK_MHZ 24

Functions Documentation

function `bsp_camera_start`

Initialize camera.

esp_err_t bsp_camera_start (
    void
) 

Camera sensor initialization.

:battery: Battery

Some boards with battery support can measure the battery voltage using an ADC channel. BSP provides a simple API for this:

/* Initialize the battery voltage measurement */
bsp_voltage_init();

/* Read battery voltage in millivolts */
int voltage = bsp_voltage_battery_get();

Battery API Reference

Functions

Type	Name
int	bsp_voltage_battery_get (void) Get battery voltage.
esp_err_t	bsp_voltage_init (void) Init voltage measurements.

Macros

Type	Name
define	BSP_BATTERY_VOLTAGE_CHANNEL (ADC_CHANNEL_2)
define	BSP_BATTERY_VOLTAGE_DIV (2)

Functions Documentation

function `bsp_voltage_battery_get`

Get battery voltage.

int bsp_voltage_battery_get (
    void
) 

Note:

bsp_voltage_init() must be called first

Returns:

Resulting voltage in [mV] or -1 on error

function `bsp_voltage_init`

Init voltage measurements.

esp_err_t bsp_voltage_init (
    void
) 

ADC configuration and calibration

Note:

If the calibration fails, voltage can’t be measured

Returns:

true Calibration OK

Returns:

false Calibration failed

Returns:

ESP_OK On success
ESP_ERR_INVALID_ARG Invalid arguments
ESP_ERR_NO_MEM No memory
ESP_ERR_NOT_FOUND ADC peripheral to be claimed is already in use
ESP_ERR_NOT_SUPPORTED ADC scheme required eFuse bits not burnt

Others API Reference

Structures and Types

Type	Name
enum	bsp_feature_t

Functions

Type	Name
esp_err_t	bsp_feature_enable (bsp_feature_t feature, bool enable) Enable selected feature.

Structures and Types Documentation

enum `bsp_feature_t`

enum bsp_feature_t {
    BSP_FEATURE_SD,
    BSP_FEATURE_LCD,
    BSP_FEATURE_CAMERA
};

Functions Documentation

function `bsp_feature_enable`

Enable selected feature.

esp_err_t bsp_feature_enable (
    bsp_feature_t feature,
    bool enable
) 

Parameters:

feature Feature for enablement
enable Enable/disable selected feature

Returns:

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

This site is open source. Improve this page.

esp-bsp

API Reference

Overview

General

Pinout

I2C

ADC

Features

Identification

Board Name API Reference

Macros

:1234: Capabilities

Capabilities API Reference

Macros

ADC API Reference

Functions

Macros

Functions Documentation

function bsp_adc_get_handle

function bsp_adc_initialize

I2C API Reference

Functions

Macros

Functions Documentation

function bsp_i2c_deinit

function bsp_i2c_get_handle

function bsp_i2c_init

:floppy_disk: SD Card and SPIFFS

SPIFFS Initialization / Deinitialization

SD Card Initialization / Deinitialization

After Mounting

SD Card and SPIFFS API Reference

Structures and Types

Functions

Macros

Structures and Types Documentation

struct bsp_sdcard_cfg_t

Functions Documentation

function bsp_sdcard_get_handle

function bsp_sdcard_get_sdmmc_host

function bsp_sdcard_get_sdspi_host

function bsp_sdcard_mount

function bsp_sdcard_sdmmc_get_slot

function bsp_sdcard_sdmmc_mount

function bsp_sdcard_sdspi_get_slot

function bsp_sdcard_sdspi_mount

function bsp_sdcard_unmount

function bsp_spiffs_mount

function bsp_spiffs_unmount

:musical_note: Audio

Initialization

Example of audio usage

Speaker

Microphone

Audio API Reference

Functions

Macros

Functions Documentation

function bsp_audio_codec_microphone_init

function bsp_audio_get_codec_itf

function bsp_audio_init

:pager: Display and Touch

Initialization

Initialization without LVGL - NoGLIB BSP

Set Brightness

LVGL API Usage (only when initialized with LVGL)

Screen rotation (only when initialized with LVGL)

Available constants

Display and Touch API Reference

Structures and Types

Functions

Macros

Structures and Types Documentation

struct bsp_display_cfg_t

struct bsp_display_config_t

Functions Documentation

function bsp_display_backlight_off

function bsp_display_backlight_on

function bsp_display_brightness_init

function bsp_display_brightness_set

function `bsp_adc_get_handle`

function `bsp_adc_initialize`

function `bsp_i2c_deinit`

function `bsp_i2c_get_handle`

function `bsp_i2c_init`

struct `bsp_sdcard_cfg_t`

function `bsp_sdcard_get_handle`

function `bsp_sdcard_get_sdmmc_host`

function `bsp_sdcard_get_sdspi_host`

function `bsp_sdcard_mount`

function `bsp_sdcard_sdmmc_get_slot`

function `bsp_sdcard_sdmmc_mount`

function `bsp_sdcard_sdspi_get_slot`

function `bsp_sdcard_sdspi_mount`

function `bsp_sdcard_unmount`

function `bsp_spiffs_mount`

function `bsp_spiffs_unmount`

function `bsp_audio_codec_microphone_init`

function `bsp_audio_get_codec_itf`

function `bsp_audio_init`

struct `bsp_display_cfg_t`

struct `bsp_display_config_t`

function `bsp_display_backlight_off`

function `bsp_display_backlight_on`

function `bsp_display_brightness_init`

function `bsp_display_brightness_set`

function `bsp_display_enter_sleep`

function `bsp_display_exit_sleep`

function `bsp_display_get_input_dev`

function `bsp_display_lock`

function `bsp_display_new`

function `bsp_display_rotate`

function `bsp_display_start`

function `bsp_display_start_with_config`

function `bsp_display_unlock`

enum `bsp_button_t`

function `bsp_iot_button_create`

enum `bsp_led_effect_t`

enum `bsp_led_t`

function `bsp_led_indicator_create`

function `bsp_led_set`

function `bsp_camera_start`

function `bsp_voltage_battery_get`

function `bsp_voltage_init`

enum `bsp_feature_t`

function `bsp_feature_enable`