GitHub - espressif/esp-bsp: Board support components for Espressif development boards (original) (raw)

pre-commit

ESP-BSP: Espressif's Board Support Packages

HOW TO USE BOARDS EXAMPLES CONTRIBUTING LVGL port LCD drivers

This repository provides Board Support Packages (BSPs) for various Espressif and M5Stack development boards. Written in C, each BSP offers a unified and consistent API to simplify the initialization and use of common onboard peripherals such as displays, touch panels, audio codecs, SD cards, and selected sensors. The goal is to streamline development and reduce hardware-specific boilerplate, enabling faster prototyping and cleaner application code.

Main Purpose of BSP

  1. Simplify development on Espressif and M5Stack boards by providing ready-to-use peripheral initialization.
  2. Enable quick project startup on supported development boards, with an easy path to migrate to custom hardware.
  3. Facilitate cross-board development by offering a common API, making it easier to build and maintain projects for multiple boards.

Supported IDF versions

The following table shows the compatibility of this BSP with different ESP-IDF versions:

4.x 5.0 5.1 5.2 5.3 5.4 5.5
❌ ❌ ✔️ ✔️ ✔️ ✔️ ✔️

Supported Boards

Board name SoC Supported Features Photo
ESP-BOX-3 esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (es8311)🔘 Button 📟 LCD Display (st7789, ili9341)🎮 IMU 💾 uSD Card ☝️ Display Touch (tt21100, gt911)
ESP32-C3-LCDKit esp32c3 🎵 Audio 🔈 Audio Speaker 📟 LCD Display (gc9a01)⚪ Knob 💡 LED
ESP32-LyraT esp32 🎵 Audio 🎤 Audio Microphone (es8388)🔈 Audio Speaker (es8388)🔘 Button 💡 LED 💾 uSD Card
ESP32-P4 Function EV Board esp32p4 🎵 Audio 🎤 Audio Microphone (es8311)🔈 Audio Speaker (es8311)📟 LCD Display (ek79007, ili9881c, lt8912b)💾 uSD Card ☝️ Display Touch (gt911)
ESP32-S2-Kaluga Kit esp32s2 🎵 Audio 🎤 Audio Microphone (es8311)🔈 Audio Speaker (es8311)🔘 Button 📷 Camera 📟 LCD Display (st7789)💡 LED
ESP32-S3-EYE esp32s3 🎵 Audio 🎤 Audio Microphone 🔘 Button 📷 Camera 📟 LCD Display (st7789)🎮 IMU 💾 uSD Card
ESP32-S3-KORVO-1 esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (es8311)🔘 Button 💡 LED 💾 uSD Card
ESP32-S3-Korvo-2 esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (es8311)🔘 Button 📷 Camera 📟 LCD Display (ili9341)💡 LED 💾 uSD Card ☝️ Display Touch (tt21100)
ESP32-S3-LCD-EV-Board esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (es8311)🔘 Button 📟 LCD Display ☝️ Display Touch
ESP32-S3-USB-OTG esp32s3 🔋 Battery 🔘 Button 📟 LCD Display (st7789)💡 LED 💾 uSD Card
DevKit BSP - 🔘 Button 💡 LED
Generic BSP - 🔘 Button 📟 LCD Display (st7789, ili9341, gc9a01)💡 LED ☝️ Display Touch (tt21100, gt1151, gt911, cst816s, ft5x06)
ESP-WROVER-KIT esp32 🔘 Button 📟 LCD Display (st7789)💡 LED 💾 uSD Card
M5 Atom S3 esp32s3 🔘 Button 📟 LCD Display (gc9a01)
M5Dial esp32s3 🔘 Button 📟 LCD Display (gc9a01)⚪ Knob ☝️ Display Touch (ft5x06)
M5Stack Core esp32 🔈 Audio Speaker 🔘 Button 📟 LCD Display (ili9341)💾 uSD Card
M5Stack Core2 esp32 🎵 Audio 🔈 Audio Speaker 📟 LCD Display (ili9341)💾 uSD Card ☝️ Display Touch (ft5x06)
M5Stack CoreS3 esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (aw88298)📷 Camera 📟 LCD Display (ili9341)💾 uSD Card ☝️ Display Touch (ft5x06)

Deprecated Boards

Board name SoC Supported Features Photo
ESP-BOX esp32s3 🎵 Audio 🎤 Audio Microphone (es7210)🔈 Audio Speaker (es8311)🔘 Button 📟 LCD Display (st7789)🎮 IMU ☝️ Display Touch (tt21100)
ESP-BOX-Lite esp32s3 🎵 Audio 🎤 Audio Microphone (es7243e)🔈 Audio Speaker (es8156)🔘 Button 📟 LCD Display (st7789)
ESP32-Azure IoT Kit esp32 🔘 Button 📟 LCD Display (ssd1306)🎮 IMU 💡 LED 💾 uSD Card ⚫ SENSOR_HUMIDITY ⚫ SENSOR_LIGHT ⚫ SENSOR_MAG ⚫ SENSOR_PRESSURE ⚫ SENSOR_TEMPERATURE

Examples

The best way to start with ESP-BSP is by trying one of the available examples on your board. Each example includes a README.md file listing supported boards and usage instructions.

Here is a summary of the available examples:

Example Description Supported Boards Try with ESP Launchpad
Audio Example Play and record WAV file 4 boardsesp32_lyratesp32_s2_kaluga_kitesp32_s3_korvo_1esp32_s3_korvo_2 Flash Example
Display Example Show an image on the screen with a simple startup animation (LVGL) 16 boardsesp-boxesp-box-3esp-box-liteesp32_c3_lcdkitesp32_p4_function_ev_boardesp32_s2_kaluga_kitesp32_s3_eyeesp32_s3_korvo_2esp32_s3_lcd_ev_boardesp32_s3_usb_otgesp_wrover_kitm5_atom_s3m5dialm5stack_corem5stack_core_2m5stack_core_s3 Flash Example
Display, Audio and Photo Example Complex demo: browse files from filesystem and play/display JPEG, WAV, or TXT files (LVGL) 7 boardsesp-boxesp-box-3esp-box-liteesp32_s3_korvo_2esp32_s3_lcd_ev_boardm5stack_core_2m5stack_core_s3 Flash Example
Camera Example Stream camera output to display (LVGL) 4 boardsesp32_s2_kaluga_kitesp32_s3_eyeesp32_s3_korvo_2m5stack_core_s3 Flash Example
LVGL Benchmark Example Run LVGL benchmark tests 10 boardsesp-boxesp-box-3esp-box-liteesp32_p4_function_ev_boardesp32_s2_kaluga_kitesp32_s3_eyeesp32_s3_korvo_2esp32_s3_lcd_ev_boardm5dialm5stack_core_s3 -
LVGL Demos Example Run the LVGL demo player - all LVGL examples are included (LVGL) 10 boardsesp-boxesp-box-3esp-box-liteesp32_p4_function_ev_boardesp32_s2_kaluga_kitesp32_s3_eyeesp32_s3_korvo_2esp32_s3_lcd_ev_boardm5dialm5stack_core_s3 Flash Example
Display Rotation Example Rotate screen using buttons or an accelerometer (BSP_CAPS_IMU, if available) 9 boardsesp-boxesp-box-3esp-box-liteesp32_p4_function_ev_boardesp32_s3_korvo_2esp32_s3_lcd_ev_boardm5dialm5stack_corem5stack_core_s3 Flash Example
Sensors Example Display sensor data on a monochrome screen (LVGL) 1 boardesp32_azure_iot_kit Flash Example
USB HID Example USB HID demo (keyboard, mouse, or gamepad visualization using LVGL) 2 boardsesp32_p4_function_ev_boardesp32_s3_usb_otg -
Generic Button and LED Example Minimal example using the Generic BSP: button and LED control 2 boardsesp_bsp_devkitesp_bsp_generic -
MQTT Example Collect sensor data and publish to an MQTT server 1 boardesp32_azure_iot_kit -

BSP headers and options

NOTE: There can be only one BSP in a single esp-idf project.

In a custom project

Packages from this repository are uploaded to the IDF component registry. You can add them to your project via idf.py add-dependency, e.g.

    idf.py add-dependency esp_wrover_kit==1.0.0

Recommendation for custom projects

When you want to use a BSP in a real project, it is highly recommended to disable configuration option CONFIG_BSP_ERROR_CHECK in menuconfig. You should check all returned error codes from all BSP functions you call. Otherwise, if the option CONFIG_BSP_ERROR_CHECK is enabled, any error encountered in a BSP will abort the program.

Compiling project for multiple BSPs

⚠️ Experimental feature: This feature is under development!

A single project can be run on multiple different development boards, if the boards contain the features required by the project (such as audio, display, camera...). For this purpose, idf.py is extended by examples/bsp_ext.py which allows you to build an example for your specific BSP. Example command for display e.g.:

idf.py -D SDKCONFIG_DEFAULTS=sdkconfig.bsp.esp_wrover_kit build

In case you want to build locally for multiple boards at the same time, it is useful to have separate build directories for each BSP configuration. In order to achieve this, you can extend the above command like this:

idf.py -B build/wrover_kit -D SDKCONFIG_DEFAULTS=sdkconfig.bsp.esp_wrover_kit build

Note: This feature is not yet integrated to idf.py by default. If you want to use it, you must set your environmental variable IDF_EXTRA_ACTIONS_PATH to path to esp-bsp/examples/bsp_ext.py.

Copyrights and License

All original source code in this repository is Copyright (c) Espressif Systems (Shanghai) Co. Ltd., and is licensed under the Apache 2.0 license.