/esp-bsp

Board support components for Espressif development boards

Primary LanguageCOtherNOASSERTION

pre-commit

ESP-BSP: Espressif's Board Support Packages

Board support packages for development boards using Espressif's SoCs, written in C.

Supported boards

Board name SoC Features Photo
ESP-WROVER-KIT ESP32 LCD display, uSD card slot
ESP-BOX ESP32-S3 LCD display with touch, audio codec + power amplifier,
accelerometer and gyroscope
ESP-BOX-Lite ESP32-S3 LCD display, audio codec + power amplifier
ESP32-Azure IoT Kit ESP32 OLED display, uSD card slot, accelerometer,
magnetometer, humidity, pressure, light
and temperature sensors
ESP32-S2-Kaluga Kit ESP32-S2 LCD display, audio codec + power amplifier,
smart LED and camera
ESP32-S3-USB-OTG ESP32-S3 LCD display, uSD card slot, USB-OTG
ESP32-S3-EYE ESP32-S3 LCD display, camera, uSD card slot, microphone and accelerometer
ESP32-S3-LCD-EV-BOARD ESP32-S3 LCD display with touch, audio codec + power amplifier
ESP32-S3-Korvo-2 ESP32-S3 LCD display, camera, uSD card slot, microphone, audio codec + power amplifier
ESP32-LyraT ESP32 uSD card slot, microphone, audio codec + power amplifier
ESP32-C3-LCDKit ESP32-C3 LCD display with encoder, IR, PDM audio

LCD displays and TOUCH

LVGL port LCD drivers

The BSP repository includes a lot of LCD and Touch driver components. The list of available and planned LCDs is here.

We offer seemless integration of LVGL graphical library into esp-idf applications in LVGL port component.

Moreover, LVGL port includes recommendations and tips for increasing graphical performance.

How to use

Examples

Best way to start with ESP-BSP is trying one of the examples on your board. Every example contains README.md with a list of supported boards. Here is the summary of the available examples:

Example Supported boards
audio ESP32-S3-Korvo-2
display WROVER-KIT
display_camera Kaluga-kit
display_audio_photo ESP-BOX
display_rotation ESP-BOX
display_lvgl_demos ESP32-S3-LCD-EV-BOARD
mqtt_example Azure-IoT-kit
sensors_example Azure-IoT-kit

BSP headers

Each BSP provides its header file in 'bsp' subfolder, so it can be included as follows: #include "bsp/name-of-the-bsp.h". For you convenience, each BSP also provides a wrapper header, which has the same name for all BSPs: #include "bsp/esp-bsp.h".

BSPs that contain LCD screen or touchscreen also provide bsp/display.h and bsp/touch.h. These files provide functions for LCD or touchscreen initialization without LVGL graphics library, which is used by default.

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

Alternatively, you can create idf_component.yml file manually, such as in this example.

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.

Migration to ESP-IDF v5.0

ESP-IDF v5.0 brings a lot of new features, but, as the bump in major version suggests, also a lot of breaking changes.

ESP-BSP is kept up-to-date with the latest ESP-IDF version, but some breaking changes in ESP-BSP API are inevitable. Usually, BSPs compatible with IDF v5.0 are version 2. If you want to use BSP with IDF v4.4 you can still use version 1 of the particular BSP. If you are interested in BSP examples for IDF v4.4, you can git checkout tag examples_v4.4.

More information about ESP-IDF breaking changes can be found in the official migration guide.

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.

Additional information

More information about idf-component-manager can be found in Espressif API guide or PyPi registry.

You can find more information about idf.py extensions here.

Contributing to ESP-BSP

Please check CONTRIBUTING.md if you'd like to contribute to ESP-BSP.

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.