Merge branch 'feature/add_adc_channel_label' into 'main'

feat(esp_board_manager): Add adc channel label for audio codec

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

Author: jason-mao

packages/esp_board_manager/CHANGELOG.md

@@ -7,6 +7,10 @@
 - Add custom device type with test support
 - Add gpio expander device type with test support
 - Add camera device type with test support, support dvp bus type now
+- Instead of modifying idf_component.yml, the board manager uses a Kconfig option to handle dynamic dependencies
+- Add `adc_channel_labels` field to audio codec for better channel identification
+- Add board selection priority documentation and sdkconfig troubleshooting guide
+- Instead of copying board source files to gen_bmgr_codes, now reference them directly via SRC_DIRS and INCLUDE_DIRS to avoid duplication.
 
 ### Supported Boards
 - **ESP32-S3 Korvo2 V3**: Full LCD, LCD Touch, DVP Camera support

packages/esp_board_manager/README.md

@@ -286,6 +286,27 @@ The ESP Board Manager supports board configuration through three different path
 2. **User Project Components**: Custom boards defined in project components, path like `{PROJECT_ROOT}/components/{component_name}/boards`
 3. **Custom Customer Path**: External board definitions in custom locations. User-specified path via `-c` argument in `gen_bmgr_config_codes.py` to set the custom path.
 
+### Board Selection Priority
+
+When multiple boards with the same name exist across different paths, the ESP Board Manager follows a specific priority order to determine which board configuration to use:
+
+**Priority Order (Highest to Lowest):**
+
+1. **Custom Customer Path** (Highest Priority)
+   - Boards specified via `-c` argument
+   - Example: `idf.py gen-bmgr-config -b my_board -c /path/to/custom/boards`
+
+2. **User Project Components** (Medium Priority)
+   - Boards in project components: `{PROJECT_ROOT}/components/{component_name}/boards`
+   - These override main boards with the same name
+
+3. **Main Boards Directory** (Lowest Priority)
+   - Built-in boards: `esp_board_manager/boards`
+   - Used as fallback when no other version exists
+
+**Important Notes:**
+- **No duplicate warnings**: The system silently uses the higher priority board without warning about duplicates
+
 ### Verify and Use New Board
 
 1. **Verify Board Configuration**
@@ -544,7 +565,13 @@ If `idf.py gen-bmgr-config` is not recognized:
 2. Ensure your project has a `components/gen_bmgr_codes` folder with generated files. These files are generated by running `idf.py gen-bmgr-config -b YOUR_BOARD`.
 
 ### **Switching Boards**
-Using `idf.py gen-bmgr-config -b` is strongly recommended. Using `idf.py menuconfig` to select boards may result in dependency errors.
+Using `idf.py gen-bmgr-config -b` is required. Using `idf.py menuconfig` to select boards may result in dependency errors.
+
+### "sdkconfig file not found"
+
+If you see the error `sdkconfig file not found at [path]`, this means that the ESP Board Manager will create the default device and peripheral dependencies based on your selected board YAML files.
+
+**Note:** The `sdkconfig` file is automatically generated by ESP-IDF when you run `idf.py menuconfig`, `idf.py set-target xxx`, or `idf.py build` for the first time in a project.
 
 ## License
 

packages/esp_board_manager/README_CN.md

@@ -25,7 +25,7 @@ esp_board_manager/
 ├── include/
 │   ├── esp_board_manager.h    # 主板级管理器 API
 │   ├── esp_board_periph.h     # 外设管理
-│   ├── esp_board_device.h    # 设备管理
+│   ├── esp_board_device.h     # 设备管理
 │   ├── esp_board_manager_err.h        # 统一错误管理系统
 │   └── esp_board_manager_defs.h       # 关键字列表
 ├── peripherals/               # 外设实现
@@ -286,6 +286,27 @@ ESP Board Manager 支持通过三个不同的路径位置进行板级配置，
 2. **用户项目组件**: 在项目组件中定义的自定义板级，路径如 `{PROJECT_ROOT}/components/{component_name}/boards`
 3. **自定义客户路径**: 自定义位置的外部板级定义。用户通过 `gen_bmgr_config_codes.py` 中的 `-c` 参数指定路径来设置自定义路径。
 
+### 板级选择优先级
+
+当不同路径中存在同名板级时，ESP Board Manager 遵循特定的优先级顺序来确定使用哪个板级配置：
+
+**优先级顺序（从高到低）：**
+
+1. **自定义客户路径**（最高优先级）
+   - 通过 `-c` 参数指定的板级
+   - 示例：`idf.py gen-bmgr-config -b my_board -c /path/to/custom/boards`
+
+2. **用户项目组件**（中等优先级）
+   - 项目组件中的板级：`{PROJECT_ROOT}/components/{component_name}/boards`
+   - 这些会覆盖同名的主板级
+
+3. **主板级目录**（最低优先级）
+   - 内置板级：`esp_board_manager/boards`
+   - 当没有其他版本时作为后备使用
+
+**重要说明：**
+- **无重复警告**：系统会静默使用高优先级板级，不会警告重复项
+
 ### 验证和使用新板级
 
 1. **验证板级配置**
@@ -544,7 +565,13 @@ ESP Board Manager 的未来开发计划：
 2. 确保您的项目有 `components/gen_bmgr_codes` 文件夹，其中包含生成的文件。这些文件是通过运行 `idf.py gen-bmgr-config -b YOUR_BOARD` 生成的。
 
 ### **切换开发板**
-强烈建议使用 `idf.py gen-bmgr-config -b`。使用 `idf.py menuconfig` 选择板级可能会导致依赖错误。
+必须使用 `idf.py gen-bmgr-config -b`。使用 `idf.py menuconfig` 选择板级可能会导致依赖错误。
+
+### "sdkconfig 文件未找到"
+
+如果您看到错误 `sdkconfig file not found at [path]`，这意味着 ESP Board Manager 将根据您选择的板级 YAML 文件创建默认的设备和外设依赖关系。
+
+**注意:** 当您在项目中首次运行 `idf.py menuconfig`、`idf.py set-target xxx` 或 `idf.py build` 时，ESP-IDF 会自动生成 `sdkconfig` 文件。
 
 ## 许可证
 

packages/esp_board_manager/boards/echoear_core_board_v1_0/board_devices.yaml

@@ -50,9 +50,10 @@ devices:
     config:
       adc_enabled: true
       adc_max_channel: 4
-      # The channel mask, 1-enable, 0-disable, from right to left layout: mic0,mic1,mic2,mic3
+      # The channel mask, 1-enable, 0-disable
       # e.g."0111", bit0: Mic0 enable, bit1: Mic1 enable, bit2: Mic2 enable, bit3: Mic3 enable, bit4: Mic4 disable
       adc_channel_mask: "0111"           # Mic0, Mic1, Mic2 enable
+      adc_channel_labels: ['NA', 'RE', 'FR', 'FL']  # MSB ~ LSB
       adc_init_gain: 0                   # dB
 
     # I2S interface configuration
@@ -127,6 +128,6 @@ devices:
     type: ledc_ctrl
     version: default
     config:
-      default_percent: 100  # 0-100, default 0 percent
+      default_percent: 100                # 0-100, default 0 percent
     peripherals:
-      - name: ledc_backlight               # LEDC peripheral for GPIO 44
+      - name: ledc_backlight              # LEDC peripheral for GPIO 44

packages/esp_board_manager/boards/echoear_core_board_v1_2/board_devices.yaml

@@ -64,10 +64,11 @@ devices:
     config:
       adc_enabled: true
       adc_max_channel: 4
-      # The channel mask, 1-enable, 0-disable, from right to left layout: mic0,mic1,mic2,mic3
+      # The channel mask, 1-enable, 0-disable
       # e.g."0111", bit0: Mic0 enable, bit1: Mic1 enable, bit2: Mic2 enable, bit3: Mic3 enable, bit4: Mic4 disable
       adc_channel_mask: "0111"         # Mic0, Mic1, Mic2 enable
-      adc_init_gain: 0                   # dB
+      adc_channel_labels: ['NA', 'RE', 'FR', 'FL'] # MSB ~ LSB
+      adc_init_gain: 0                 # dB
 
     # I2S interface configuration
     peripherals:

packages/esp_board_manager/boards/esp32_c5_spot/board_devices.yaml

@@ -17,6 +17,7 @@ devices:
       # The channel mask, 1-enable, 0-disable, from right to left layout: mic0,mic1,mic2,mic3
       # e.g. "0111", bit0: Mic0 enable, bit1: Mic1 enable, bit2: Mic2 enable, bit3: Mic3 enable, bit4: Mic4 disable
       adc_channel_mask: "1"            # Mic0 enable
+      adc_channel_labels: ['FC']
       dac_enabled: true
       dac_max_channel: 1
       # DAC channel mask, 1-enable, 0-disable, layout: left,right

packages/esp_board_manager/boards/esp32_s3_korvo2_v3/board_devices.yaml

@@ -17,7 +17,7 @@ devices:
       dac_enabled: true
       dac_max_channel: 1
       # DAC channel mask, 1-enable, 0-disable, layout: left,right
-      dac_channel_mask: "1"     # Left enable
+      dac_channel_mask: "1"        # Left enable
 
     # Power amplifier configuration
     peripherals:
@@ -41,6 +41,7 @@ devices:
       adc_enabled: true
       adc_max_channel: 4
       adc_channel_mask: "0111"
+      adc_channel_labels: ['NA', 'RE', 'FR', 'FL'] # MSB ~ LSB
       adc_init_gain: 0           # dB
 
     # Power amplifier configuration
@@ -61,7 +62,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
@@ -119,10 +120,10 @@ devices:
     config:
       # esp_lcd_panel_io_i2c_config_t fields for touch communication
       io_i2c_config:
-        dev_addr: 0x24            
+        dev_addr: 0x24
         lcd_cmd_bits: 16                  # Bit-width of LCD command
         peripherals:
-          - name: i2c_master                   # I2C peripheral for touch communication
+          - name: i2c_master              # I2C peripheral for touch communication
 
       # esp_lcd_touch_config_t fields for touch configuration
       touch_config:
@@ -131,7 +132,7 @@ devices:
         flags:
           swap_xy: false
           mirror_x: true
-          mirror_y: false      
+          mirror_y: false
 
   - name: camera_sensor
     type: camera

packages/esp_board_manager/boards/esp32_s3_korvo2l/board_devices.yaml

@@ -14,9 +14,10 @@ devices:
     config: &es8311_config
       adc_enabled: true
       adc_max_channel: 1
-      # The channel mask, 1-enable, 0-disable，from right to left layout: mic0,mic1,mic2,mic3
+      # The channel mask, 1-enable, 0-disable
       # e.g.“0111”, bit0: Mic0 enable, bit1: Mic1 enable, bit2: Mic2 enable, bit3: Mic3 enable, bit4: Mic4 disable
-      adc_channel_mask: "1"     # Mic0, Mic1 disable
+      adc_channel_mask: "1"            # Mic0 enable
+      adc_channel_labels: ['RE','FC']  # Mic0 and reference enable, MSB ~ LSB
 
       dac_enabled: true
       dac_max_channel: 1
@@ -68,7 +69,7 @@ devices:
       partition_label: NULL           # The partition label for the SPIFFS filesystem
       format_if_mount_failed: true
 
-  - name: my_custom_sensor          # The name of the device, must be unique
+  - name: my_custom_sensor         # The name of the device, must be unique
     type: custom                   # The type of the device, must be unique
     chip: esp32s3                  # Optional: Name of chip
     version: default               # Optional: Parser version to use

packages/esp_board_manager/boards/esp_box_3/board_devices.yaml

@@ -43,9 +43,10 @@ devices:
     config:
       adc_enabled: true
       adc_max_channel: 4
-      # The channel mask, 1-enable, 0-disable，from right to left layout: mic0,mic1,mic2,mic3
+      # The channel mask, 1-enable, 0-disable
       # e.g."0111", bit0: Mic0 enable, bit1: Mic1 enable, bit2: Mic2 enable, bit3: Mic3 enable, bit4: Mic4 disable
-      adc_channel_mask: "0011"
+      adc_channel_mask: "0111"
+      adc_channel_labels: ['NA', 'RE', 'FR', 'FL'] # MSB ~ LSB
       adc_init_gain: 0           # dB
 
     # Power amplifier configuration
@@ -61,7 +62,7 @@ devices:
     type: fatfs_sdcard
     version: default
     config:
-      bus_width: 4            # 1, 4, 8, not used on SPI type
+      bus_width: 4                 # 1, 4, 8, not used on SPI type
       pins:
         clk: 11   # GPIO_NUM_15
         cmd: 14   # GPIO_NUM_7
@@ -85,12 +86,12 @@ devices:
       io_spi_config:
         cs_gpio_num: 5                   # GPIO14 - LCD_CS (BSP_LCD_CS)
         dc_gpio_num: 4                   # GPIO45 - LCD_DC (BSP_LCD_DC)
-        spi_mode: 0                       # Traditional SPI mode (0~3)
-        pclk_hz: 20000000                 # Frequency of pixel clock
+        spi_mode: 0                      # Traditional SPI mode (0~3)
+        pclk_hz: 20000000                # Frequency of pixel clock
         flags:
           sio_mode: true                 # Single line mode
         peripherals:
-          - name: spi_display                  # SPI peripheral for LCD communication
+          - name: spi_display            # SPI peripheral for LCD communication
 
       lcd_panel_config:
         reset_gpio_num: 48
@@ -116,7 +117,7 @@ devices:
         dev_addr: [0x5D, 0x14]            # GT911 I2C address (ESP_LCD_TOUCH_IO_I2C_GT911_ADDRESS)
         lcd_cmd_bits: 16                  # Bit-width of LCD command
         peripherals:
-          - name: i2c_master                   # I2C peripheral for touch communication
+          - name: i2c_master              # I2C peripheral for touch communication
 
       # esp_lcd_touch_config_t fields for touch configuration
       touch_config:

packages/esp_board_manager/boards/esp_box_3/board_peripherals.yaml

@@ -25,15 +25,15 @@ peripherals:
 
       # Slot configuration
       data_bit_width: 16              # Data bit width (valid data bits per sample)
-      slot_bit_width: I2S_SLOT_BIT_WIDTH_AUTO            # Total bits per slot (AUTO or specific value)
+      slot_bit_width: I2S_SLOT_BIT_WIDTH_AUTO       # Total bits per slot (AUTO or specific value)
       slot_mode: I2S_SLOT_MODE_STEREO               # MONO or STEREO,I2S_SLOT_MODE_STEREO
-      slot_mask: I2S_STD_SLOT_BOTH                 # LEFT, RIGHT, or BOTH slots
+      slot_mask: I2S_STD_SLOT_BOTH                  # LEFT, RIGHT, or BOTH slots
       ws_width: 16                    # WS signal width in BCLK ticks
 
       # GPIO configuration
       pins:
         mclk: 2                       # GPIO number for MCLK
-        bclk: 17                       # GPIO number for BCLK
+        bclk: 17                      # GPIO number for BCLK
         ws: 45                        # GPIO number for WS
         dout: 15                      # GPIO number for DATA out
         din: 16                       # GPIO number for DATA in
@@ -53,25 +53,25 @@ peripherals:
       # spi_bus_config_t fields
       spi_bus_config:
         spi_port: SPI2_HOST               # 0: SPI1_HOST, 1: SPI2_HOST, 2: SPI3_HOST
-        data0_io_num: 6                  # MOSI_IO_NUM
-        sclk_io_num: 7                   # SPI Clock signal
-        max_transfer_sz: 72000             # Maximum transfer size in bytes
+        data0_io_num: 6                   # MOSI_IO_NUM
+        sclk_io_num: 7                    # SPI Clock signal
+        max_transfer_sz: 72000            # Maximum transfer size in bytes
 
   # PA CONTROL
   - name: gpio_pa_control
     type: gpio
     role: io
     config:
       pin: 46                      # GPIO pin number
-      mode: GPIO_MODE_OUTPUT           # GPIO mode
-      pull_up: true              # Enable pull-up resistor
+      mode: GPIO_MODE_OUTPUT       # GPIO mode
+      pull_up: true                # Enable pull-up resistor
 
   # CHIP BLACKLIGHT POWER CONTROL
   - name: gpio_backlight_control
     type: gpio
     role: io
     config:
-      pin: 47                           # GPIO47 - BL_EN (CHIP BLACKLIGHT POWER CONTROL)
+      pin: 47                      # GPIO47 - BL_EN (CHIP BLACKLIGHT POWER CONTROL)
       mode: GPIO_MODE_OUTPUT
       default_level: 1
 
@@ -80,7 +80,7 @@ peripherals:
     type: gpio
     role: io
     config:
-      pin: 43                           # GPIO43 - SD power control
+      pin: 43                          # GPIO43 - SD power control
       mode: GPIO_MODE_OUTPUT
       default_level: 1