Merge branch 'feature/bsp_in_example' into 'master'

i2s: Add BSP support for es8311 example

Closes BSP-165

See merge request espressif/esp-idf!21279

examples/peripherals/i2s/i2s_codec/i2s_es8311/README.md

@@ -26,6 +26,7 @@ For more details, see [ES8311 datasheet](http://www.everest-semi.com/pdf/ES8311%
 ### Hardware Required
 
 * A development board with any supported Espressif SOC chip (see `Supported Targets` table above)
+    * The example can be preconfigured for [ESP-BOX](https://components.espressif.com/components/espressif/esp-box), [ESP32-S2-Kaluga-kit](https://components.espressif.com/components/espressif/esp32_s2_kaluga_kit) and [ESP32-S3-LCD-EV-board](https://components.espressif.com/components/espressif/esp32_s3_lcd_ev_board). More information is in 'Configure the Project' section.
 * A USB cable for power supply and programming.
 * A board with ES8311 codec, mic and earphone interface(e.g. ESP-LyraT-8311A extension board).
 
@@ -60,12 +61,12 @@ Note: Since ESP32-C3 & ESP32-H4 board does not have GPIO 16/17, you can use othe
 
 This example is based on [es8311 component](https://components.espressif.com/component/espressif/es8311)
 
-The component can be installed by esp component manager. Since this example already installed it, no need to re-installed it again, but if you want to install this component in your own project, you can input the following command:
+The component can be installed by [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). This example already includes it. If you want to install [es8311 component](https://components.espressif.com/components/espressif/es8311) separately in your project, you can input the following command:
 ```
-idf.py add-dependency espressif/es8311^1.0.0
+idf.py add-dependency "espressif/es8311^1.0.0"
 ```
 
-If the dependency is added, you can check `idf_component.yml` for more detail. When building this example or other projects with managed components, the component manager will search for the required components online and download them into the `managed_componets` folder.
+If the dependency is added, you can check `idf_component.yml` for more detail. When building this example or other projects with managed components, the component manager will search for the required components online and download them into the `managed_components` folder.
 
 ### Configure the Project
 
@@ -80,6 +81,8 @@ You can find configurations for this example in 'Example Configutation' tag.
 
 * In 'Voice volume', you can set the volum between 0 to 100.
 
+* In 'Enable Board Support Package (BSP) support' you can enable support for BSP. You can pick specific BSP in [idf_component.yml](main/idf_component.yml).
+
 ### Build and Flash
 
 Build the project and flash it to the board, then run monitor tool to view serial output:

examples/peripherals/i2s/i2s_codec/i2s_es8311/main/Kconfig.projbuild

@@ -9,6 +9,7 @@ menu "Example Configuration"
         config EXAMPLE_MODE_MUSIC
             bool "music"
         config EXAMPLE_MODE_ECHO
+            depends on !EXAMPLE_BSP
             bool "echo"
     endchoice
 
@@ -55,4 +56,9 @@ menu "Example Configuration"
         help
             Set voice volume
 
+    config EXAMPLE_BSP
+        bool "Enable Board Support Package (BSP) support"
+        default n
+        help
+            Use BSP to setup all hardware settings. Specific board must be selected in main/idf_component.yml file.
 endmenu

examples/peripherals/i2s/i2s_codec/i2s_es8311/main/example_config.h

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+#pragma once
+
+#include "sdkconfig.h"
+
+/* Example configurations */
+#define EXAMPLE_RECV_BUF_SIZE   (2400)
+#define EXAMPLE_SAMPLE_RATE     (16000)
+#define EXAMPLE_MCLK_MULTIPLE   (384) // If not using 24-bit data width, 256 should be enough
+#define EXAMPLE_MCLK_FREQ_HZ    (EXAMPLE_SAMPLE_RATE * EXAMPLE_MCLK_MULTIPLE)
+#define EXAMPLE_VOICE_VOLUME    CONFIG_EXAMPLE_VOICE_VOLUME
+#if CONFIG_EXAMPLE_MODE_ECHO
+#define EXAMPLE_MIC_GAIN        CONFIG_EXAMPLE_MIC_GAIN
+#endif
+
+
+#if !defined(CONFIG_EXAMPLE_BSP)
+
+/* I2C port and GPIOs */
+#define I2C_NUM         (0)
+#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
+#define I2C_SCL_IO      (GPIO_NUM_16)
+#define I2C_SDA_IO      (GPIO_NUM_17)
+#else
+#define I2C_SCL_IO      (GPIO_NUM_6)
+#define I2C_SDA_IO      (GPIO_NUM_7)
+#endif
+
+/* I2S port and GPIOs */
+#define I2S_NUM         (0)
+#define I2S_MCK_IO      (GPIO_NUM_0)
+#define I2S_BCK_IO      (GPIO_NUM_4)
+#define I2S_WS_IO       (GPIO_NUM_5)
+#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
+#define I2S_DO_IO       (GPIO_NUM_18)
+#define I2S_DI_IO       (GPIO_NUM_19)
+#else
+#define I2S_DO_IO       (GPIO_NUM_2)
+#define I2S_DI_IO       (GPIO_NUM_3)
+#endif
+
+
+#else // CONFIG_EXAMPLE_BSP
+#include "bsp/esp-bsp.h"
+#define I2C_NUM BSP_I2C_NUM
+
+#endif // CONFIG_EXAMPLE_BSP

examples/peripherals/i2s/i2s_codec/i2s_es8311/main/i2s_es8311_example.c

@@ -6,44 +6,15 @@
 
 #include <stdio.h>
 #include <string.h>
+#include "sdkconfig.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "driver/i2s_std.h"
 #include "esp_system.h"
 #include "esp_check.h"
 #include "es8311.h"
+#include "example_config.h"
 
-/* I2C port and GPIOs */
-#define I2C_NUM         (0)
-#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
-#define I2C_SCL_IO      (GPIO_NUM_16)
-#define I2C_SDA_IO      (GPIO_NUM_17)
-#else
-#define I2C_SCL_IO      (GPIO_NUM_6)
-#define I2C_SDA_IO      (GPIO_NUM_7)
-#endif
-
-/* I2S port and GPIOs */
-#define I2S_NUM         (0)
-#define I2S_MCK_IO      (GPIO_NUM_0)
-#define I2S_BCK_IO      (GPIO_NUM_4)
-#define I2S_WS_IO       (GPIO_NUM_5)
-#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
-#define I2S_DO_IO       (GPIO_NUM_18)
-#define I2S_DI_IO       (GPIO_NUM_19)
-#else
-#define I2S_DO_IO       (GPIO_NUM_2)
-#define I2S_DI_IO       (GPIO_NUM_3)
-#endif
-/* Example configurations */
-#define EXAMPLE_RECV_BUF_SIZE   (2400)
-#define EXAMPLE_SAMPLE_RATE     (16000)
-#define EXAMPLE_MCLK_MULTIPLE   (384) // If not using 24-bit data width, 256 should be enough
-#define EXAMPLE_MCLK_FREQ_HZ    (EXAMPLE_SAMPLE_RATE * EXAMPLE_MCLK_MULTIPLE)
-#define EXAMPLE_VOICE_VOLUME    CONFIG_EXAMPLE_VOICE_VOLUME
-#if CONFIG_EXAMPLE_MODE_ECHO
-#define EXAMPLE_MIC_GAIN        CONFIG_EXAMPLE_MIC_GAIN
-#endif
 
 static const char *TAG = "i2s_es8311";
 static const char err_reason[][30] = {"input param is invalid",
@@ -61,7 +32,8 @@ extern const uint8_t music_pcm_end[]   asm("_binary_canon_pcm_end");
 static esp_err_t es8311_codec_init(void)
 {
     /* Initialize I2C peripheral */
-    i2c_config_t es_i2c_cfg = {
+#if !defined(CONFIG_EXAMPLE_BSP)
+    const i2c_config_t es_i2c_cfg = {
         .sda_io_num = I2C_SDA_IO,
         .scl_io_num = I2C_SCL_IO,
         .mode = I2C_MODE_MASTER,
@@ -71,11 +43,14 @@ static esp_err_t es8311_codec_init(void)
     };
     ESP_RETURN_ON_ERROR(i2c_param_config(I2C_NUM, &es_i2c_cfg), TAG, "config i2c failed");
     ESP_RETURN_ON_ERROR(i2c_driver_install(I2C_NUM, I2C_MODE_MASTER,  0, 0, 0), TAG, "install i2c driver failed");
+#else
+    ESP_ERROR_CHECK(bsp_i2c_init());
+#endif
 
     /* Initialize es8311 codec */
     es8311_handle_t es_handle = es8311_create(I2C_NUM, ES8311_ADDRRES_0);
     ESP_RETURN_ON_FALSE(es_handle, ESP_FAIL, TAG, "es8311 create failed");
-    es8311_clock_config_t es_clk = {
+    const es8311_clock_config_t es_clk = {
         .mclk_inverted = false,
         .sclk_inverted = false,
         .mclk_from_mclk_pin = true,
@@ -95,6 +70,7 @@ static esp_err_t es8311_codec_init(void)
 
 static esp_err_t i2s_driver_init(void)
 {
+#if !defined(CONFIG_EXAMPLE_BSP)
     i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM, I2S_ROLE_MASTER);
     chan_cfg.auto_clear = true; // Auto clear the legacy data in the DMA buffer
     ESP_ERROR_CHECK(i2s_new_channel(&chan_cfg, &tx_handle, &rx_handle));
@@ -120,6 +96,17 @@ static esp_err_t i2s_driver_init(void)
     ESP_ERROR_CHECK(i2s_channel_init_std_mode(rx_handle, &std_cfg));
     ESP_ERROR_CHECK(i2s_channel_enable(tx_handle));
     ESP_ERROR_CHECK(i2s_channel_enable(rx_handle));
+#else
+    ESP_LOGI(TAG, "Using BSP for HW configuration");
+    i2s_std_config_t std_cfg = {
+        .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(EXAMPLE_SAMPLE_RATE),
+        .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_STEREO),
+        .gpio_cfg = BSP_I2S_GPIO_CFG,
+    };
+    std_cfg.clk_cfg.mclk_multiple = EXAMPLE_MCLK_MULTIPLE;
+    ESP_ERROR_CHECK(bsp_audio_init(&std_cfg, &tx_handle, &rx_handle));
+    ESP_ERROR_CHECK(bsp_audio_poweramp_enable(true));
+#endif
     return ESP_OK;
 }
 

examples/peripherals/i2s/i2s_codec/i2s_es8311/main/idf_component.yml

@@ -1,17 +1,18 @@
 ## IDF Component Manager Manifest File
 dependencies:
+  idf: "^5.0"
   espressif/es8311: "^1.0.0"
-  ## Required IDF version
-  idf:
-    version: "^5.0"
-  # # Put list of dependencies here
-  # # For components maintained by Espressif:
-  # component: "~1.0.0"
-  # # For 3rd party components:
-  # username/component: ">=1.0.0,<2.0.0"
-  # username2/component2:
-  #   version: "~1.0.0"
-  #   # For transient dependencies `public` flag can be set.
-  #   # `public` flag doesn't have an effect dependencies of the `main` component.
-  #   # All dependencies of `main` are public by default.
-  #   public: true
+
+# After enabling Board Support Packages support in menuconfig, you can pick you specific BSP here
+  espressif/esp-box:
+    version: "^2"
+    rules:
+      - if: "target in [esp32s3]"
+  #espressif/esp32_s2_kaluga_kit:
+  #  version: "^2.1.1"
+  #  rules:
+  #    - if: "target in [esp32s2]"
+  #espressif/esp32_s3_lcd_ev_board:
+  #  version: "^1"
+  #  rules:
+  #    - if: "target in [esp32s3]"

examples/peripherals/i2s/i2s_codec/i2s_es8311/pytest_i2s_es8311.py

@@ -15,3 +15,19 @@ def test_i2s_es8311_example_generic(dut: Dut) -> None:
     dut.expect('i2s es8311 codec example start')
     dut.expect('-----------------------------')
     dut.expect('I \\(([0-9]+)\\) i2s_es8311: i2s driver init success')
+
+
+@pytest.mark.esp32s3
+@pytest.mark.generic
+@pytest.mark.parametrize(
+    'config',
+    [
+        'bsp',
+    ],
+    indirect=True,
+)
+def test_i2s_es8311_example_bsp(dut: Dut) -> None:
+    dut.expect('i2s es8311 codec example start')
+    dut.expect('-----------------------------')
+    dut.expect('Using BSP for HW configuration')
+    dut.expect('I \\(([0-9]+)\\) i2s_es8311: i2s driver init success')

examples/peripherals/i2s/i2s_codec/i2s_es8311/sdkconfig.ci.bsp

@@ -0,0 +1,2 @@
+CONFIG_IDF_TARGET="esp32s3"
+CONFIG_EXAMPLE_BSP=y