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:

1. Provides unified macro definitions for pins

2. Provides default peripheral configuration parameters

3. Provides unified board-level initialization interfaces

4. Provides hardware control interfaces for development boards

The following figure shows the structure of the Boards component:

Boards Component Diagram

• 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 declaration

  • board.c provides user implementation of common API (Covering default weak function), custom API function implementation

  • kconfig.in provides custom configuration items unique to the development board.

Note

The Boards component is provided in examples/common_components/boards.

Instructions

1. Initialize development board: use iot_board_init in app_main to initialize the development board. you can also do some configurations regarding this process using The Switch and Configuration of a Development Board in menuconfig;

2. Get the handle of a peripheral: use iot_board_get_handle and board_res_id_t to get peripheral resources. NULL will be returned if this peripheral is not initialized;

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

1. Select the target development board: select a development board in menuconfig->Board Options->Choose Target Board;

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

3. 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-devkitc	esp32-meshkit-sense
esp32-lcdkit
ESP32-S2 Development Boards
esp32s2-saola
ESP32-S3 Development Boards
esp32s3-devkitc-v1

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:

1. Prepare the necessary iot_board.h based on existing example;

2. Add board specific functions or cover the common weak function in board_xxx.c according to the requirements;

3. Add configuration options specific to this board in kconfig.in according to your needs;

4. Add the information of this board to Kconfig.projbuild for users;

5. Add the directory of this board to CMakeLists.txt so that it can be indexed by the build system. Please also update component.mk if you need to support the old make 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

Provide feedback about this document