Merge branch 'feature/add_idf_ext_py_for_board_manager' into 'main'

feat(esp_board_manager): Integrate board manager as IDF action with auto-discovery

See merge request adf/multimedia/esp-gmf!182

Author: jason-mao

packages/esp_board_manager/CHANGELOG.md

@@ -1,10 +1,19 @@
 # Changelog
 
-## Unreleased
+## v0.4.1
+
+### Features
+- Renamed esp_board_manager_ext.py to idf_ext.py for compatibility with ESP-IDF v6.0 auto-discovery
+- Update `Kconfig.in` with new configuration options to hide the board selection menu
+- Update the README to include information about how to add new boards and the development roadmap
+- Added the esp_board_periph_ref_handle and esp_board_periph_unref_handle APIs to obtain and release a handle
+- Added esp_board_find_utils.h and esp_board_manager_includes.h
 
 ### Bug Fixes
+- Delete only `build/CMakeCache.txt` to avoid a full clean when switching boards
 - Fixed the configuration of the sdmmc sdcard host slot, ensuring the configuration for the host slot in the yml file takes effect correctly
 - Using slot 0 to drive the sdcard for p4_function board, avoiding conflict with wifi hosted
+- Correct the error codes
 
 ## v0.4.0
 

packages/esp_board_manager/CMakeLists.txt

@@ -23,6 +23,7 @@ idf_component_register(
     INCLUDE_DIRS
         "."
         "include"
+        "private_inc"
         ${PERIPH_INCLUDES}  # Add peripheral includes
         ${DEVICE_INCLUDES}  # Add device includes
     REQUIRES

packages/esp_board_manager/README.md

@@ -53,7 +53,7 @@ esp_board_manager/
 │   ├── CMakeLists.txt
 │   └── idf_component.yml
 ├── gen_bmgr_config_codes.py   # Main code generation script (unified)
-├── esp_board_manager_ext.py   # IDF action extension
+├── idf_ext.py                 # IDF action extension (Auto-discovery in v6.0+)
 ├── README.md                  # This file
 └── README_CN.md               # Chinese version Readme
 ```
@@ -62,7 +62,9 @@ esp_board_manager/
 
 ### 1. Setup IDF Action Extension
 
-The ESP Board Manager now supports IDF action extension, providing seamless integration with the ESP-IDF build system. Set the `IDF_EXTRA_ACTIONS_PATH` environment variable to include the ESP Board Manager directory:
+The ESP Board Manager now supports IDF action extension, providing seamless integration with the ESP-IDF build system. This feature allows you to use `idf.py gen-bmgr-config` command directly instead of running the Python script manually.
+
+Set the `IDF_EXTRA_ACTIONS_PATH` environment variable to include the ESP Board Manager directory:
 
 **Ubuntu and Mac:**
 
@@ -91,7 +93,9 @@ export IDF_EXTRA_ACTIONS_PATH=YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__es
 Note:
 > **Note:** If you use `idf.py add-dependency xxx` to add **esp_board_manager** as a dependency, the directory `YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__esp_board_manager` will not be available on the first build or after cleaning the `managed_components` folder. We recommend running `idf.py set-target`, `idf.py menuconfig`, or `idf.py build` to automatically download the **esp_board_manager** component into `YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__esp_board_manager`.
 
-> **Version Requirement:** Supports ESP-IDF v5.4 and later versions
+> **Version Requirement:** Compatible with ESP-IDF v5.4 and v5.5 branches. **Note:** Versions prior to v5.4.2 or v5.5.1 may encounter Kconfig dependency issues.
+
+> **Note:** IDF action extension auto-discovery is available starting from ESP-IDF v6.0. No need to set `IDF_EXTRA_ACTIONS_PATH` beginning with IDF v6.0, as it automatically discovers the IDF action extension.
 
 If you encounter any issues, please refer to the [## Troubleshooting](#troubleshooting) section.
 
@@ -247,6 +251,9 @@ For detailed YAML configuration rules and format specifications, please refer to
    ```
 
 5. **Define Peripherals**
+   - Find similar peripheral configuration YML files in `boards` for reference
+   - Configure based on supported peripheral YML files under `peripherals`
+   The basic structure for each peripheral is as follows:
    ```yaml
    # board_peripherals.yaml
    board: <board_name>
@@ -262,6 +269,9 @@ For detailed YAML configuration rules and format specifications, please refer to
    ```
 
 6. **Define Devices**
+   - Find similar device configuration YML files in `boards` for reference
+   - Configure based on supported device YML files under `devices`
+   The basic structure for each device is as follows:
    ```yaml
    # board_devices.yaml
    board: <board_name>
@@ -288,6 +298,15 @@ For detailed YAML configuration rules and format specifications, please refer to
          - name: <peripheral_name>
     ```
 
+7. **Custom Code in Board Directory**
+   - When using certain devices, additional custom code may be required, such as for `display_lcd`, `lcd_touch`, and `custom` devices.
+   - This is to improve board adaptation, allowing users to select the actual device initialization function based on their board's specific requirements. For `display_lcd` and `lcd_touch`, refer to `esp_board_manager/boards/echoear_core_board_v1_2/setup_device.c`.
+
+8. **Custom Device Description**
+   - For devices and peripherals not yet included in esp_board_manager, it is recommended to add them through `custom` type devices.
+   - Implementation code should be placed in the `board` directory. Refer to `esp_board_manager/boards/esp32_s3_korvo2l/custom_device.c`.
+   - When the board is selected, a `gen_board_device_custom.h` header file will be generated in the `gen_bmgr_codes` directory for application use.
+
 > **⚙️ About `dependencies` Usage**
 >
 > - * The `dependencies` field in `board_devices.yaml` allows you to specify component dependencies for each device. This is especially useful for boards that require custom or local versions of components.
@@ -376,7 +395,7 @@ When multiple boards with the same name exist across different paths, the ESP Bo
 
 | Device | Type | Chip | Peripheral | Status | Description | Reference YAML |
 |--------|------|------|------------|--------|-------------|----------------|
-| Audio Codec | audio_codec | ES8311/ES7210 | i2s/i2c | ✅ Supported | Audio codec with DAC/ADC | [`dev_audio_codec.yaml`](devices/dev_audio_codec/dev_audio_codec.yaml) |
+| Audio Codec | audio_codec | ES8311/ES7210/ES8388 | i2s/i2c | ✅ Supported | Audio codec with DAC/ADC | [`dev_audio_codec.yaml`](devices/dev_audio_codec/dev_audio_codec.yaml) |
 | LCD Display | display_lcd_spi | ST77916/GC9A01 | spi | ✅ Supported | SPI LCD display | [`dev_display_lcd_spi.yaml`](devices/dev_display_lcd_spi/dev_display_lcd_spi.yaml) |
 | Touch Screen | lcd_touch_i2c | FT5x06 | i2c | ✅ Supported | I2C touch screen | [`dev_lcd_touch_i2c.yaml`](devices/dev_lcd_touch_i2c/dev_lcd_touch_i2c.yaml) |
 | SD Card | fatfs_sdcard | - | sdmmc | ✅ Supported | SD card storage | [`dev_fatfs_sdcard.yaml`](devices/dev_fatfs_sdcard/dev_fatfs_sdcard.yaml) |
@@ -564,14 +583,14 @@ python gen_bmgr_config_codes.py --sdkconfig-only
 
 ## Roadmap
 
-Future development plans for the ESP Board Manager:
-- **Build Workflow**: Improve the efficiency and streamline the build workflow
+Future development plans for the ESP Board Manager (prioritized from high to low):
+- **Support More Peripherals and Devices**: Add more peripherals, devices, and boards
+- **Web Visual Configuration**: Combine with large models to achieve visual and intelligent board configuration through web interface
+- **Documentation Enhancement**: Add more documentation, such as establishing clear rules to facilitate customer addition of peripherals and devices
+- **Enhanced Validation**: Comprehensive YAML format checking, schema validation, input validation, and enhanced rule validation
+- **Enhanced data structure**: Enhance the data or YAML structure to improve performance
 - **Version Management**: Support different version codes and parsers for devices and peripherals
 - **Plugin Architecture**: Extensible plugin system for custom device and peripheral support
-- **Enhanced Validation**: Comprehensive YAML format checking, schema validation, input validation, and enhanced rule validation with improved error reporting
-- **Enhanced Initialization Flow**: Support for skipping specific components or calling initialization on different cores
-- **Clear Definition Rules**: Establish clear rules to facilitate customer addition of peripherals and devices
-- **Extended Component Support**: Add more peripherals, devices, and boards
 
 ## Troubleshooting
 

packages/esp_board_manager/README_CN.md

@@ -53,7 +53,7 @@ esp_board_manager/
 │   ├── CMakeLists.txt
 │   └── idf_component.yml
 ├── gen_bmgr_config_codes.py   # 主代码生成脚本（统一）
-├── esp_board_manager_ext.py   # IDF action 扩展
+├── idf_ext.py                 # IDF action 扩展（v6.0+ 自动发现）
 ├── README.md                  # 此文件
 └── README_CN.md               # 中文版本说明
 ```
@@ -62,7 +62,9 @@ esp_board_manager/
 
 ### 1. 设置 IDF Action 扩展
 
-ESP Board Manager 现在支持 IDF action 扩展，提供与 ESP-IDF 构建系统的无缝集成。设置 `IDF_EXTRA_ACTIONS_PATH` 环境变量以包含 ESP Board Manager 目录：
+ESP Board Manager 现在支持 IDF action 扩展，提供与 ESP-IDF 构建系统的无缝集成。此功能允许您直接使用 `idf.py gen-bmgr-config` 命令，而无需手动运行 Python 脚本。
+
+设置 `IDF_EXTRA_ACTIONS_PATH` 环境变量以包含 ESP Board Manager 目录：
 
 **Ubuntu and Mac:**
 
@@ -90,7 +92,9 @@ export IDF_EXTRA_ACTIONS_PATH=YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__es
 
 > **注意:** 如果您使用 `idf.py add-dependency xxx` 将 **esp_board_manager** 添加为依赖组件，在首次构建或清理 `managed_components` 文件夹后，目录 `YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__esp_board_manager` 将不可见。我们建议运行 `idf.py set-target`、`idf.py menuconfig` 或 `idf.py build` 来自动将 **esp_board_manager** 组件下载到 `YOUR_PROJECT_ROOT_PATH/managed_components/XXXX__esp_board_manager`。
 
-> **版本要求:** 支持 ESP-IDF v5.4 及以后的版本
+> **版本要求:** 兼容 ESP-IDF v5.4 和 v5.5 分支。**注意:** v5.4.2 或 v5.5.1 之前的版本可能会遇到 Kconfig 依赖问题。
+
+> **注意:** IDF action 扩展自动发现功能从 ESP-IDF v6.0 开始可用。从 IDF v6.0 开始无需设置 `IDF_EXTRA_ACTIONS_PATH`，因为它会自动发现 IDF action 扩展。
 
 如果遇到任何问题，请参考 [## 故障排除](#故障排除) 部分。
 
@@ -216,6 +220,9 @@ Board Manager 的设备名称推荐用于用户项目，而外设名称不推荐
 #### 创建板级文件夹和文件
 
 1. **创建板级目录**
+- 推荐板级目录放置在项目的 components 文件下，路径可参考: `esp_board_manager/test_apps/components/board_customer`
+- 板级目录还可以放在其他位置，路径参考：`esp_board_manager/test_apps/test_custom_boards` 和 `esp_board_manager/test_apps/test_single_board`。这个路径运行命令时需要添加 `-c` 参数来指定路径，如 `test_apps` 下：`idf.py gen-bmgr-config -c test_single_board -l`
+
    ```bash
    mkdir boards/<board_name>
    cd boards/<board_name>
@@ -247,6 +254,9 @@ Board Manager 的设备名称推荐用于用户项目，而外设名称不推荐
    ```
 
 5. **定义外设**
+   - 寻找 `boards` 中相似的外设配置YML文件进行参考
+   - 基于 `peripherals` 下支持的外设 YML 进行配置
+   每个外设的基本结构如下：
    ```yaml
    # board_peripherals.yaml
    board: <board_name>
@@ -262,6 +272,9 @@ Board Manager 的设备名称推荐用于用户项目，而外设名称不推荐
    ```
 
 6. **定义设备**
+   - 寻找 `boards` 中相似的设备配置YML文件进行参考
+   - 基于 `devices` 下支持的设备 YML 进行配置
+   每个设备的基本结构如下：
    ```yaml
    # board_devices.yaml
    board: <board_name>
@@ -285,6 +298,14 @@ Board Manager 的设备名称推荐用于用户项目，而外设名称不推荐
        peripherals:
          - name: <peripheral_name>
     ```
+7. **`board` 目录中自定义代码的说明**
+   - 在使用一些设备的时候，需要额外增加自定义代码，比如 `display_lcd`, `lcd_touch` and `custom` device.
+   - 这是为了提高板子的适配，让用户根据自己板子情况选择 device 实际初始化函数，`display_lcd`, `lcd_touch` 参考 `esp_board_manager/boards/echoear_core_board_v1_2/setup_device.c`。
+
+8. **`custom` 自定义设备说明**
+   - 对于 esp_board_manager 还未包含的设备和外设，建议通过 `custom` 类型 device 进行添加
+   - 实现的代码放置在 `board` 目录下，参考 `esp_board_manager/boards/esp32_s3_korvo2l/custom_device.c`
+   - 当该 board 被选择后 `gen_bmgr_codes` 目录下会生成 `gen_board_device_custom.h` 头文件，供应用程序使用
 
 > **⚙️ 关于 `dependencies` 使用说明**
 >
@@ -382,9 +403,9 @@ ESP Board Manager 支持通过三个不同的路径位置进行板级配置，
 | SPIFFS 文件系统 | fs_spiffs | - | - | ✅ 支持 | SPIFFS 文件系统 | [`dev_fs_spiffs.yaml`](devices/dev_fs_spiffs/dev_fs_spiffs.yaml) |
 | GPIO 控制 | gpio_ctrl | - | gpio | ✅ 支持 | GPIO 控制设备 | [`dev_gpio_ctrl.yaml`](devices/dev_gpio_ctrl/dev_gpio_ctrl.yaml) |
 | LEDC 控制 | ledc_ctrl | - | ledc | ✅ 支持 | LEDC 控制设备 | [`dev_ledc_ctrl.yaml`](devices/dev_ledc_ctrl/dev_ledc_ctrl.yaml) |
-| [自定义设备](devices/dev_custom/README.md | custom | - | any | ✅ 支持 | 用户定义的自定义设备 | [`dev_custom.yaml`](devices/dev_custom/dev_custom.yaml) |
+| [自定义设备](devices/dev_custom/README.md) | custom | - | any | ✅ 支持 | 用户定义的自定义设备 | [`dev_custom.yaml`](devices/dev_custom/dev_custom.yaml) |
 | GPIO 扩展芯片 | gpio_expander | TCA9554/TCA95XX/HT8574 | i2c | ✅ 支持 | GPIO 扩展芯片 | [`dev_gpio_expander.yaml`](devices/dev_gpio_expander/dev_gpio_expander.yaml) |
-| 摄像头 | camera | - | i2c | ✅ 支持 | 摄像头设备 | [`dev_gpio_expander.yaml`](devices/dev_camera/dev_camera.yaml) |
+| 摄像头 | camera | - | i2c | ✅ 支持 | 摄像头设备 | [`dev_camera.yaml`](devices/dev_camera/dev_camera.yaml) |
 
 ### 支持的板级
 
@@ -562,14 +583,14 @@ python gen_bmgr_config_codes.py --sdkconfig-only
 
 ## 路线图
 
-ESP Board Manager 的未来开发计划：
-- **构建工作流程**: 提高效率并简化构建工作流程
+ESP Board Manager 的未来开发计划（优先级从高到低）：
+- **支持更多外设和设备**: 添加更多外设、设备和板级
+- **Web 可视化配置**: 结合大模型通过网页实现可视化和智能化的配置板子
+- **完善文档**: 增加更多说明文档，如建立明确的规则以促进客户添加外设和设备
+- **增强验证**: 全面的 YAML 格式检查、模式验证、输入验证和增强的规则验证
+- **增强数据结构**: 增强数据或 YAML 结构以提高性能
 - **版本管理**: 支持设备和外设的不同版本代码和解析器
 - **插件架构**: 用于自定义设备和外设支持的可扩展插件系统
-- **增强验证**: 全面的 YAML 格式检查、模式验证、输入验证和增强的规则验证，具有改进的错误报告
-- **增强初始化流程**: 支持跳过特定组件或在不同核心上调用初始化
-- **明确定义规则**: 建立明确的规则以促进客户添加外设和设备
-- **扩展组件支持**: 添加更多外设、设备和板级
 
 ## 故障排除
 

packages/esp_board_manager/boards/esp32_s3_korvo2_v3/board_devices.yaml

@@ -54,7 +54,7 @@ devices:
         clk: 15  # GPIO_NUM_15
         cmd: 7   # GPIO_NUM_7
         d0: 4    # GPIO_NUM_4
-  
+
   - name: gpio_expander
     chip: tca9554
     type: gpio_expander
@@ -68,7 +68,7 @@ devices:
       input_io_mask: NULL
     peripherals:
       - name: i2c_master
-        i2c_addr: [0x70, 0x7A]         # I2C address of the IO expander
+        i2c_addr: [0x70, 0x40]         # I2C address of the IO expander
 
   - name: display_lcd
     chip: ili9341

packages/esp_board_manager/boards/esp32_s3_korvo2_v3/setup_device.c

@@ -87,7 +87,7 @@ esp_err_t camera_factory_entry_t(const dev_camera_config_t *camera_cfg, dev_came
     ESP_LOGI(TAG, "Creating camera driver...");
 
     void *i2c_handle = NULL;
-    esp_err_t ret = esp_board_periph_get_handle(camera_cfg->config.dvp.i2c_name, &i2c_handle);
+    esp_err_t ret = esp_board_periph_ref_handle(camera_cfg->config.dvp.i2c_name, &i2c_handle);
     if (ret != ESP_OK || !i2c_handle) {
         ESP_LOGE(TAG, "Failed to get I2C handle\n");
         return -1;

packages/esp_board_manager/devices/dev_audio_codec/dev_audio_codec.c

@@ -14,6 +14,7 @@
 #include "esp_board_periph.h"
 #include "esp_board_manager_defs.h"
 #include "es8389_codec.h"
+#include "esp_board_device.h"
 
 static const char *TAG = "DEV_AUDIO_CODEC";
 
@@ -234,12 +235,12 @@ int dev_audio_codec_init(void *cfg, int cfg_size, void **device_handle)
     audio_codec_i2s_cfg_t i2s_cfg = {0};
     if (strcmp(codec_cfg->name, ESP_BOARD_DEVICE_NAME_AUDIO_ADC) == 0) {
         ESP_LOGI(TAG, "ADC is ENABLED");
-        esp_board_periph_get_handle(codec_cfg->i2s_cfg.name, &i2s_cfg.rx_handle);
+        esp_board_periph_ref_handle(codec_cfg->i2s_cfg.name, &i2s_cfg.rx_handle);
 
         dev_type |= ESP_CODEC_DEV_TYPE_IN;
     } else if (strcmp(codec_cfg->name, ESP_BOARD_DEVICE_NAME_AUDIO_DAC) == 0) {
         codec_handles->gpio_if = (audio_codec_gpio_if_t *)audio_codec_new_gpio();
-        esp_board_periph_get_handle(codec_cfg->i2s_cfg.name, &i2s_cfg.tx_handle);
+        esp_board_periph_ref_handle(codec_cfg->i2s_cfg.name, &i2s_cfg.tx_handle);
         ESP_LOGI(TAG, "DAC is ENABLED");
         dev_type |= ESP_CODEC_DEV_TYPE_OUT;
     }
@@ -249,7 +250,7 @@ int dev_audio_codec_init(void *cfg, int cfg_size, void **device_handle)
              codec_cfg->name, codec_cfg->i2s_cfg.name, i2s_cfg.rx_handle, i2s_cfg.tx_handle, codec_handles->data_if);
 
     audio_codec_i2c_cfg_t i2c_cfg = {0};
-    esp_board_periph_get_handle(codec_cfg->i2c_cfg.name, &i2c_cfg.bus_handle);
+    esp_board_periph_ref_handle(codec_cfg->i2c_cfg.name, &i2c_cfg.bus_handle);
     i2c_cfg.addr = codec_cfg->i2c_cfg.address;
     codec_handles->ctrl_if = (audio_codec_ctrl_if_t *)audio_codec_new_i2c_ctrl(&i2c_cfg);
 
@@ -300,6 +301,7 @@ int dev_audio_codec_init(void *cfg, int cfg_size, void **device_handle)
 int dev_audio_codec_deinit(void *device_handle)
 {
     dev_audio_codec_handles_t *codec_handles = (dev_audio_codec_handles_t *)device_handle;
+
     esp_codec_dev_delete(codec_handles->codec_dev);
     codec_handles->codec_dev = NULL;
     audio_codec_delete_codec_if(codec_handles->codec_if);
@@ -311,6 +313,19 @@ int dev_audio_codec_deinit(void *device_handle)
         codec_handles->gpio_if = NULL;
     }
     audio_codec_delete_data_if(codec_handles->data_if);
+
+    const char *name = NULL;
+    const esp_board_device_handle_t *device_handle_struct = esp_board_device_find_by_handle(device_handle);
+    if (device_handle_struct) {
+        name = device_handle_struct->name;
+    }
+    dev_audio_codec_config_t *cfg = NULL;
+    esp_board_device_get_config(name, (void **)&cfg);
+    if (cfg) {
+        esp_board_periph_unref_handle(cfg->i2s_cfg.name);
+        esp_board_periph_unref_handle(cfg->i2c_cfg.name);
+    }
+
     codec_handles->data_if = NULL;
     free(codec_handles);
     return 0;

packages/esp_board_manager/devices/dev_camera/dev_camera.c

@@ -9,6 +9,8 @@
 #include "esp_log.h"
 #include "esp_video_init.h"
 #include "dev_camera.h"
+#include "esp_board_device.h"
+#include "esp_board_periph.h"
 
 static const char *TAG = "DEV_CAMERA";
 
@@ -47,6 +49,18 @@ int dev_camera_deinit(void *device_handle)
     }
     dev_camera_handle_t *camera_handles = (dev_camera_handle_t *)device_handle;
     esp_video_deinit();
+
+    const char *name = NULL;
+    const esp_board_device_handle_t *device_handle_struct = esp_board_device_find_by_handle(device_handle);
+    if (device_handle_struct) {
+        name = device_handle_struct->name;
+    }
+    dev_camera_config_t *cfg = NULL;
+    esp_board_device_get_config(name, (void **)&cfg);
+    if (cfg) {
+        esp_board_periph_unref_handle(cfg->config.dvp.i2c_name);
+    }
+
     free(camera_handles);
     return 0;
 }