esp-bsp

API Reference

| :1234: [CAPABILITIES](#1234-capabilities) | :floppy_disk: [SD CARD AND SPIFFS](#floppy_disk-sd-card-and-spiffs) | :pager: [DISPLAY AND TOUCH](#pager-display-and-touch) | :radio_button: [BUTTONS](#radio_button-buttons) | :bulb: [LEDS](#bulb-leds) | :electric_plug: [USB](#electric_plug-usb) | :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.

[!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):

[!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_S3_USB_OTG

: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 0
define BSP_CAPS_AUDIO_MIC 0
define BSP_CAPS_AUDIO_SPEAKER 0
define BSP_CAPS_BAT 1
define BSP_CAPS_BUTTONS 1
define BSP_CAPS_DISPLAY 1
define BSP_CAPS_IMU 0
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_1

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.

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

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

Macros

Type Name
define BSP_SDSPI_HOST (SPI2_HOST)
define BSP_SD_CLK (GPIO_NUM_36)
define BSP_SD_CMD (GPIO_NUM_35)
define BSP_SD_D0 (GPIO_NUM_37)
define BSP_SD_D1 (GPIO_NUM_38)
define BSP_SD_D2 (GPIO_NUM_33)
define BSP_SD_D3 (GPIO_NUM_34)
define BSP_SD_MOUNT_POINT CONFIG_BSP_SD_MOUNT_POINT
define BSP_SD_SPI_CLK (GPIO_NUM_36)
define BSP_SD_SPI_CS (GPIO_NUM_34)
define BSP_SD_SPI_MISO (GPIO_NUM_37)
define BSP_SD_SPI_MOSI (GPIO_NUM_35)
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:

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:

Get SD card SPI host config.

void bsp_sdcard_get_sdspi_host (
    const int slot,
    sdmmc_host_t *config
)

Parameters:

Mount microSD card to virtual file system.

esp_err_t bsp_sdcard_mount (
    void
)

Returns:

Get SD card MMC slot config.

void bsp_sdcard_sdmmc_get_slot (
    const int slot,
    sdmmc_slot_config_t *config
)

Parameters:

Mount microSD card to virtual file system (MMC mode)

esp_err_t bsp_sdcard_sdmmc_mount (
    bsp_sdcard_cfg_t *cfg
)

Parameters:

Returns:

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:

Mount microSD card to virtual file system (SPI mode)

esp_err_t bsp_sdcard_sdspi_mount (
    bsp_sdcard_cfg_t *cfg
)

Parameters:

Returns:

Unmount microSD card from virtual file system.

esp_err_t bsp_sdcard_unmount (
    void
)

Returns:

Mount SPIFFS to virtual file system.

esp_err_t bsp_spiffs_mount (
    void
)

Returns:

Unmount SPIFFS from virtual file system.

esp_err_t bsp_spiffs_unmount (
    void
)

Returns:

:pager: Display and Touch

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:

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.
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_9)
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_DC (GPIO_NUM_4)
define BSP_LCD_DRAW_BUFF_DOUBLE (1)
define BSP_LCD_DRAW_BUFF_SIZE (BSP_LCD_H_RES * 30)
define BSP_LCD_H_RES (240)
define BSP_LCD_PIXEL_CLOCK_HZ (40 * 1000 * 1000)
define BSP_LCD_RST (GPIO_NUM_8)
define BSP_LCD_SPI_CLK (GPIO_NUM_6)
define BSP_LCD_SPI_CS (GPIO_NUM_5)
define BSP_LCD_SPI_MOSI (GPIO_NUM_7)
define BSP_LCD_SPI_NUM (SPI3_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:

struct bsp_display_config_t

BSP display configuration structure.

Variables:

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:

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:

Initialize display’s brightness.

esp_err_t bsp_display_brightness_init (
    void
)

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

Returns:

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:

Returns:

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:

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:

Returns:

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:

Initialize display.

lv_display_t * bsp_display_start (
    void
)

This function initializes SPI, display controller and starts LVGL handling task.

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:

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:

Buttons API Reference

Structures and Types

Type Name
enum bsp_button_t

Functions

Type Name
bool bsp_button_get (const bsp_button_t btn)
Get button’s state.
esp_err_t bsp_button_init (void)
Set button’s GPIO as input.
esp_err_t bsp_iot_button_create (button_handle_t btn_array, int *btn_cnt, int btn_array_size)
Initialize all buttons.

Structures and Types Documentation

enum bsp_button_t

enum bsp_button_t {
    BSP_BUTTON_OK = GPIO_NUM_0,
    BSP_BUTTON_DW = GPIO_NUM_11,
    BSP_BUTTON_UP = GPIO_NUM_10,
    BSP_BUTTON_MENU = GPIO_NUM_14,
    BSP_USB_OVERCURRENT = GPIO_NUM_21,
    BSP_BUTTON_NUM = 5
};

Functions Documentation

function bsp_button_get

Get button’s state.

bool bsp_button_get (
    const bsp_button_t btn
)

Note: For LCD panel button which is defined as BSP_BUTTON_MAIN, bsp_display_start should be called before call this function.

Parameters:

Returns:

true Button pressed

Returns:

false Button released

function bsp_button_init

Set button’s GPIO as input.

esp_err_t bsp_button_init (
    void
)

Returns:

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

Note:

For LCD panel button which is defined as BSP_BUTTON_MAIN, bsp_display_start should be called before call this function.

Parameters:

Returns:

: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:

Leds API Reference

Structures and Types

Type Name
enum bsp_led_t
typedef enum bsp_led_t bsp_led_t

Functions

Type Name
esp_err_t bsp_led_set (const bsp_led_t led_io, const bool on)
Turn LED on/off.
esp_err_t bsp_leds_init (void)
Set LED’s GPIOs as output push-pull.

Structures and Types Documentation

enum bsp_led_t

enum bsp_led_t {
    BSP_LED_GREEN = GPIO_NUM_15,
    BSP_LED_YELLOW = GPIO_NUM_16
};

typedef bsp_led_t

typedef enum bsp_led_t bsp_led_t;

Functions Documentation

function bsp_led_set

Turn LED on/off.

esp_err_t bsp_led_set (
    const bsp_led_t led_io,
    const bool on
)

Parameters:

Returns:

Set LED’s GPIOs as output push-pull.

esp_err_t bsp_leds_init (
    void
)

Returns:

:electric_plug: USB

Boards with USB support define macros for USB pins, such as BSP_USB_POS and BSP_USB_NEG, and may also provide control APIs for enabling or disabling USB functionality.

/* Initialize USB in device mode and enable power */
bsp_usb_host_start(BSP_USB_HOST_POWER_MODE_USB_DEV, true);

...
/* Deinitialize and stop USB */
bsp_usb_host_stop();

[!NOTE] Not all BSPs implement USB support or provide power control. Refer to the board’s documentation and the BSP header files for available functions and supported modes.

For more USB-related APIs and configuration options, check the corresponding BSP header files.

USB API Reference

Structures and Types

Type Name
enum bsp_usb_host_power_mode_t
Power modes of USB Host connector.
typedef enum bsp_usb_host_power_mode_t bsp_usb_host_power_mode_t
Power modes of USB Host connector.

Functions

Type Name
esp_err_t bsp_usb_host_power_mode (bsp_usb_host_power_mode_t mode, bool limit_500mA)
Select power source of USB Host connector.
esp_err_t bsp_usb_host_start (bsp_usb_host_power_mode_t mode, bool limit_500mA)
Start USB host.
esp_err_t bsp_usb_host_stop (void)
Stop USB host.
esp_err_t bsp_usb_mode_select_device (void)
Switch ESP32-S3-USB-OTG to USB device mode.
esp_err_t bsp_usb_mode_select_host (void)
Switch ESP32-S3-USB-OTG to USB host mode.

Macros

Type Name
define BSP_USB_DEV_VBUS_EN (GPIO_NUM_12)
define BSP_USB_HOST_VOLTAGE (GPIO_NUM_1)
define BSP_USB_HOST_VOLTAGE_DIV (3.7f)
define BSP_USB_LIMIT_EN (GPIO_NUM_17)
define BSP_USB_MODE_SEL (GPIO_NUM_18)
define BSP_USB_NEG (GPIO_NUM_19)
define BSP_USB_POS (GPIO_NUM_20)

Structures and Types Documentation

enum bsp_usb_host_power_mode_t

Power modes of USB Host connector.

enum bsp_usb_host_power_mode_t {
    BSP_USB_HOST_POWER_MODE_OFF,
    BSP_USB_HOST_POWER_MODE_BATTERY,
    BSP_USB_HOST_POWER_MODE_USB_DEV
};

For easy setup of USB host mode use bsp_usb_host_start() function.

Use this function only if you want to change power mode on already initialized board, or in custom USB Host lib configurations.

Note:

USB Host connector can’t be powered from debugging USB port (USB-UART0)

Note:

If selecting battery mode, the battery slide switch must be switched on

typedef bsp_usb_host_power_mode_t

Power modes of USB Host connector.

typedef enum bsp_usb_host_power_mode_t bsp_usb_host_power_mode_t;

For easy setup of USB host mode use bsp_usb_host_start() function.

Use this function only if you want to change power mode on already initialized board, or in custom USB Host lib configurations.

Note:

USB Host connector can’t be powered from debugging USB port (USB-UART0)

Note:

If selecting battery mode, the battery slide switch must be switched on

Functions Documentation

function bsp_usb_host_power_mode

Select power source of USB Host connector.

esp_err_t bsp_usb_host_power_mode (
    bsp_usb_host_power_mode_t mode,
    bool limit_500mA
)

Parameters:

Returns:

Start USB host.

esp_err_t bsp_usb_host_start (
    bsp_usb_host_power_mode_t mode,
    bool limit_500mA
)

This is a one-stop-shop function that will configure the board for USB Host mode and start USB Host library

Parameters:

Returns:

Stop USB host.

esp_err_t bsp_usb_host_stop (
    void
)

USB Host lib will be uninstalled and power from connector removed.

Returns:

Switch ESP32-S3-USB-OTG to USB device mode.

esp_err_t bsp_usb_mode_select_device (
    void
)

Returns:

Switch ESP32-S3-USB-OTG to USB host mode.

esp_err_t bsp_usb_mode_select_host (
    void
)

For easy setup of USB host mode use bsp_usb_host_start() function.

Use this in custom USB Host lib configurations.

Returns:

: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.
int bsp_voltage_usb_get (void)
Get USB device connector voltage.

Macros

Type Name
define BSP_BATTERY_BOOST_EN (GPIO_NUM_13)
define BSP_BATTERY_VOLTAGE (GPIO_NUM_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:

Get USB device connector voltage.

int bsp_voltage_usb_get (
    void
)

Note:

bsp_voltage_init() must be called first

Returns:

Resulting voltage in [mV] or -1 on error

This site is open source. Improve this page.