From 67d95c609be072b812acc4d55376b693c9c0fb58 Mon Sep 17 00:00:00 2001 From: hou wen xiang Date: Fri, 29 Jun 2018 16:21:31 +0800 Subject: [PATCH] doc(i2s): update README.md file of i2s related examples. --- examples/peripherals/i2s/README.md | 70 ++++++++- .../peripherals/i2s/main/i2s_example_main.c | 14 +- examples/peripherals/i2s_adc_dac/README.md | 138 +++++++++++------- 3 files changed, 160 insertions(+), 62 deletions(-) diff --git a/examples/peripherals/i2s/README.md b/examples/peripherals/i2s/README.md index 40288e353a..8f16374f10 100644 --- a/examples/peripherals/i2s/README.md +++ b/examples/peripherals/i2s/README.md @@ -1,11 +1,67 @@ # I2S Example -### This example shows: +(See the README.md file in the upper level 'examples' directory for more information about examples.) -Init and using I2S module: - -* Generate 100Hz triangle wave in a channel, and sine wave in another, with 36Khz sample rates. Change bits per sample every 5 seconds - -* You can change bits per sample and sample rates with `i2s_set_clk` - +In this example, we generate a 100Hz triangle and sine wave and send it out from left and right channels at a sample rate of 36kHz through the I2S bus. +## How to Use Example + +### Hardware Required + +* A development board with ESP32 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.) +* A USB cable for power supply and programming + +### Configure the Project + +``` +make menuconfig +``` + +* Set serial port under Serial Flasher Options. + +### Build and Flash + +Build the project and flash it to the board, then run monitor tool to view serial output: + +``` +make -j4 flash monitor +``` + +(To exit the serial monitor, type ``Ctrl-]``.) + +See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. + +## Example Output + +Running this example, you will see the Bits per Sample changes every 5 seconds after you have run this example. You can use `i2s_set_clk` to change the Bits per Sample and the Sample Rate. The output log can be seen below: + +``` +Test bits=24 free mem=293780, written data=2880 +I2S: DMA Malloc info, datalen=blocksize=480, dma_buf_count=6 +I2S: PLL_D2: Req RATE: 36000, real rate: 37878.000, BITS: 24, CLKM: 11, BCK: 8, MCLK: 13837837.838, SCLK: 1818144.000000, diva: 64, divb: 36 + +Test bits=32 free mem=292336, written data=2880 +I2S: DMA Malloc info, datalen=blocksize=480, dma_buf_count=6 +I2S: PLL_D2: Req RATE: 36000, real rate: 36764.000, BITS: 32, CLKM: 17, BCK: 4, MCLK: 9216921.692, SCLK: 2352896.000000, diva: 64, divb: 23 + +Test bits=16 free mem=293772, written data=1440 +I2S: DMA Malloc info, datalen=blocksize=240, dma_buf_count=6 +I2S: PLL_D2: Req RATE: 36000, real rate: 36764.000, BITS: 16, CLKM: 17, BCK: 8, MCLK: 9216921.692, SCLK: 1176448.000000, diva: 64, divb: 23 +``` + +If you have a logic analyzer, you can use a logic analyzer to grab online data. The following table describes the pins we use by default (Note that you can also use other pins for the same purpose). + +| pin name| function | gpio_num | +|:---:|:---:|:---:| +| WS |word select| GPIO_NUM_25 | +| SCK |continuous serial clock| GPIO_NUM_26 | +| SD |serial data| GPIO_NUM_22 | + +## Troubleshooting + +* Program upload failure + + * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. + +For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/i2s/main/i2s_example_main.c b/examples/peripherals/i2s/main/i2s_example_main.c index 8c0c54d45f..36bbabc18b 100644 --- a/examples/peripherals/i2s/main/i2s_example_main.c +++ b/examples/peripherals/i2s/main/i2s_example_main.c @@ -20,7 +20,11 @@ #define SAMPLE_RATE (36000) #define I2S_NUM (0) #define WAVE_FREQ_HZ (100) -#define PI 3.14159265 +#define PI (3.14159265) +#define I2S_BCK_IO (GPIO_NUM_26) +#define I2S_WS_IO (GPIO_NUM_25) +#define I2S_DO_IO (GPIO_NUM_22) +#define I2S_DI_IO (-1) #define SAMPLE_PER_CYCLE (SAMPLE_RATE/WAVE_FREQ_HZ) @@ -92,10 +96,10 @@ void app_main() .intr_alloc_flags = ESP_INTR_FLAG_LEVEL1 //Interrupt level 1 }; i2s_pin_config_t pin_config = { - .bck_io_num = 26, - .ws_io_num = 25, - .data_out_num = 22, - .data_in_num = -1 //Not used + .bck_io_num = I2S_BCK_IO, + .ws_io_num = I2S_WS_IO, + .data_out_num = I2S_DO_IO, + .data_in_num = I2S_DI_IO //Not used }; i2s_driver_install(I2S_NUM, &i2s_config, 0, NULL); i2s_set_pin(I2S_NUM, &pin_config); diff --git a/examples/peripherals/i2s_adc_dac/README.md b/examples/peripherals/i2s_adc_dac/README.md index ad448f217c..2d3b05bd94 100644 --- a/examples/peripherals/i2s_adc_dac/README.md +++ b/examples/peripherals/i2s_adc_dac/README.md @@ -1,53 +1,91 @@ -# I2S built-in ADC/DAC Example - - ---- - -* This is an example of: - * Recording sound from ADC - * Replay the recorded sound via DAC - * Play an audio file in flash - ---- - -* Run this example - * Set partition table to "partitions_adc_dac_example.csv" in menuconfig, or rename sdkconfig.default to sdkconfig directly. - * Set IDF_PATH and run "make flash" ---- - -* This example will execute the following steps: - 1. Erase flash - 2. Record audio from ADC and save in flash - 3. Read flash and replay the sound via DAC - 4. Play an example audio file(file format: 8bit/8khz/single channel) - 5. Loop back to step 3 - ---- - -* Hardware connection: - - | ESP32 | Microphone + amplifier | amplifier + speaker | - |--|--|--| - | GPIO36(ADC1CH0 input) | data output pin | | - | GPIO25(DAC1 output) | | right channel speaker input| - | GPIO26(DAC2 output) | | left channel speaker input| - ---- - -* How to generate audio files: - - * tools/generate_audio_file.py is an example of generate audio table from .wav files. - * In this example, the wav file must be in 16k/16bit mono format. - * generate_audio_file.py will bundle the wav files into a single table named audio_example_file.h - * Since the ADC can only play 8-bit data, the script will scale each 16-bit value to a 8-bit value. - * Since the ADC can only output positive value, the script will turn a signed value into an unsigned value. - ---- - -* Note: - * DAC can only play 8-bit data, so the wav file data are scaled to 8-bit data. - * I2S DMA can only output 16-bit/32-bit data to DAC, DAC will only take the highest 8-bit data and output accordingly. - * Before I2S DMA can output data stream to DAC, the data format should be converted to 16-bit or 32-bit by padding zeros. +# I2S Built-in ADC/DAC Example +(See the README.md file in the upper level 'examples' directory for more information about examples.) +In this example, we configure I2S to work in I2S_ADC and I2S_DAC modes and then: +* recording sound from ADC, +* playing the recorded sound, +* playing an audio file in flash via DAC. +#### Note: +The `tools` directory contains `generate_audio_file.py` script for generating audio files: + + * The script provides an example of generating audio tables from `.wav` files. + * In this example, the `wav` file must be in 16k/16bit mono format. + * The script will bundle the `wav` files into a single table named `audio_example_file.h`. + * Since the ADC can only play 8-bit data, the script will scale each 16-bit value to a 8-bit value. + * The script will covert all signed values into unsigned values because only positive values will be output by the ADC. + +## How to Use Example + +### Hardware Required + +* A development board with ESP32 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.) +* A USB cable for power supply and programming +* A microphone (with amplifier) and one or two speaker(s) for testing. + +The following is the hardware connection: + +|hardware|module|GPIO| +|:---:|:---:|:---:| +|Microphone|ADC1_CH0|GPIO36| +|speaker(R)|DAC1|GPIO25| +|speaker(L)|DAC2|GPIO26| + +### Configure the Project + +``` +make menuconfig +``` + +* Set serial port under Serial Flasher Options, the flash size should be set to 4 MB. +* Select "Custom partition table CSV" and rename "Custom partition CSV file" to "partitions_adc_dac_example.csv". + +(Note that you can use `sdkconfig.defaults`) + +### Build and Flash + +Build the project and flash it to the board, then run monitor tool to view serial output: + +``` +make -j4 flash monitor +``` + +(To exit the serial monitor, type ``Ctrl-]``.) + +See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. + +## Example Output + +Reset your development board. The application it will first record the sound through the microphone. Then it will play the recorded sound, and finally a piece of audio stored in the flash. The following is the output log: + +``` +partiton addr: 0x00110000; size: 2097152; label: storage +Erasing flash +partiton addr: 0x00110000; size: 2097152; label: storage +Erase size: 323584 Bytes +I2S: PLL_D2: Req RATE: 16000, real rate: 1004.000, BITS: 16, CLKM: 83, BCK: 60, MCLK: 83.333, SCLK: 32128.000000, diva: 64, divb: 21 +Sound recording 5% +Sound recording 10% +... +Sound recording 97% +Sound recording 102% +playing: 0 % +playing: 1 % +playing: 2 % +... +playing: 96 % +playing: 97 % +playing: 98 % +Playing file example: +I2S: PLL_D2: Req RATE: 16000, real rate: 1004.000, BITS: 16, CLKM: 83, BCK: 60, MCLK: 83.333, SCLK: 32128.000000, diva: 64, divb: 21 +``` + +## Troubleshooting + +* Program upload failure + + * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. + +For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. -- 2.40.0