Boards Component
This document mainly introduces the use of a board support component (Boards). As a common component of examples, this component can provide unified pin macro definitions and hardware-independent initialization operations to applications. Applications developed based on this component are compatible with different development boards at the same time with the following features:
Provides unified macro definitions for pins
Provides default peripheral configuration parameters
Provides unified board-level initialization interfaces
Provides hardware control interfaces for development boards
The following figure shows the structure of the Boards component:
The Boards component contains the following:
board_common.h
, contains the function declaration of the common API;board_common.c
, contains the function implementation of the common API (weak function);Kconfig.projbuild
, contains common configuration items;
The subfolders named after the development board name includes the following:
iot_board.h
provides the gpio definition of the development board, and the board’s unique custom API function declarationboard.c
provides user implementation of common API (Covering default weak function), custom API function implementationkconfig.in
provides custom configuration items unique to the development board.
Note
The Boards component is provided in examples/common_components/boards
.
Instructions
Initialize development board: use
iot_board_init
inapp_main
to initialize the development board. you can also do some configurations regarding this process using The Switch and Configuration of a Development Board inmenuconfig
;Get the handle of a peripheral: use
iot_board_get_handle
andboard_res_id_t
to get peripheral resources.NULL
will be returned if this peripheral is not initialized;Operate on peripherals with handles directly.
Example:
void app_main(void)
{
/*initialize board with default parameters,
you can use menuconfig to choose a target board*/
esp_err_t err = iot_board_init();
if (err != ESP_OK) {
goto error;
}
/*get the i2c0 bus handle with a board_res_id,
BOARD_I2C0_ID is declared in board_res_id_t in each iot_board.h*/
bus_handle_t i2c0_bus_handle = (bus_handle_t)iot_board_get_handle(BOARD_I2C0_ID);
if (i2c0_bus_handle == NULL) {
goto error;
}
/*
* use initialized peripheral with handles directly,
* no configurations required anymore.
*/
}
The Switch and Configuration of a Development Board
For applications developed basing on Boards
, the following steps can be used to switch and configure boards:
Select the target development board: select a development board in
menuconfig->Board Options->Choose Target Board
;Configure the development board parameters:
Board Common Options
contains common configurations, such as if enable i2c0 during the initialization of the development board;XXX Board Options
contains the development board-specific configurations, such as switching the power supply status of the development board, etc.Use
idf.py build flash monitor
to recompile and download the code.
Note
The default target of this build system is ESP32
, please set the target before building via idf.py set-target esp32s2
if you need to use ESP32-S2
.
Supported Development Boards
ESP32 Development Boards |
|
ESP32-S2 Development Boards |
|
ESP32-S3 Development Boards |
|
Add a New Development Board
A new development board can be added to quickly adapt to applications developed basing on the Boards
component.
The main process is as follows:
Prepare the necessary
iot_board.h
based on existing example;Add board specific functions or cover the common weak function in
board_xxx.c
according to the requirements;Add configuration options specific to this board in
kconfig.in
according to your needs;Add the information of this board to
Kconfig.projbuild
for users;Add the directory of this board to
CMakeLists.txt
so that it can be indexed by the build system. Please also updatecomponent.mk
if you need to support the oldmake
system.
Note
An easy way is to directly copy files of the existing development boards in Boards
and make simple modifications to add your new board.
Component Dependencies
Common dependencies: bus, button, led_strip
Adapted IDF Versions
ESP-IDF v4.4 and later versions.
Supported Chips
ESP32
ESP32-S2
ESP32-S3