ESP32微控制器 上 I2S 支持的用法和示例_设计_文档_相关文件_下载

# MicroPython I2S Guide and Examples for ESP32 **Deprecation Notice: These examples are associated with a MicroPython PR that is now obsolete. I2S is now supported in official MicroPython builds, since July 5, 2021. Binaries can be downloaded at [MicroPython downloads](https://micropython.org/download/). A [new set of examples](https://github.com/miketeachman/micropython-i2s-examples) is available that works with Pyboards and the ESP32.** This guide outlines the capabilities of a new MicroPython [I2S](https://en.wikipedia.org/wiki/I%C2%B2S) class that has been developed for the MicroPython project. The I2S class works on ESP32 processors and is implemented using Espressif's [ESP-IDF API](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2s.html). To use I2S with MicroPython you will need to make a custom MicroPython build and integrate a [pull request](https://github.com/micropython/micropython/pull/4471) into the build. Or, download and program your ESP32 board using one of the pre-built [firmware binaries](firmware). *** **Example usage - Read audio samples from an I2S microphone module** ``` from machine import I2S from machine import Pin bck_pin = Pin(14) # Bit clock output ws_pin = Pin(13) # Word clock output sdin_pin = Pin(12) # Serial data input audio_in = I2S(I2S.NUM0, # create I2S peripheral to read audio bck=bck_pin, ws=ws_pin, sdin=sdin_pin, # sample data from an INMP441 standard=I2S.PHILIPS, mode=I2S.MASTER_RX, # microphone module dataformat=I2S.B32, channelformat=I2S.RIGHT_LEFT, samplerate=16000, dmacount=16,dmalen=256) samples = bytearray(2048) # bytearray to receive audio samples num_bytes_read = audio_in.readinto(samples) # read audio samples from microphone # note: blocks until sample array is full # - see optional timeout argument # to configure maximum blocking duration ``` *** **Example usage - Play audio samples through a speaker using an I2S amplifier module** ``` from machine import I2S from machine import Pin bck_pin = Pin(14) # Bit clock output ws_pin = Pin(13) # Word clock output sdout_pin = Pin(12) # Serial data output audio_out = I2S(I2S.NUM1, # create I2S peripheral to write audio bck=bck_pin, ws=ws_pin, sdout=sdout_pin, # sample data to an Adafruit I2S Amplifier standard=I2S.PHILIPS, mode=I2S.MASTER_TX, # breakout board, dataformat=I2S.B16, # based on MAX98357A device channelformat=I2S.ONLY_RIGHT, samplerate=16000, dmacount=16,dmalen=512) samples = bytearray(1024) # bytearray containing audio samples to transmit num_bytes_written = audio_out.write(samples) # write audio samples to amplifier # note: blocks until sample array is emptied # - see optional timeout argument # to configure maximum blocking duration ``` # class I2S ## Constructor ``` class machine.I2S(id, bck, ws, [sdin], [sdout], [standard=I2S.PHILIPS], mode, dataformat, channelformat, samplerate, [dmacount=16], [dmalen=64], [apllrate=0]) ``` Construct and return a new I2S object with the given arguments: * **id** specifies I2S peripheral instance * **bck** pin object for the bit clock output * **ws** pin object for the word select output * **sdin** pin object for the serial data input (optional) * **sdout** pin object for the serial data output (optional) * **standard** protocol used by the I2S peripheral (optional) * **mode** specifies receive or transmit * **dataformat** number of bits in each sample * **channelformat** specifies audio format, e.g. stereo, mono * **samplerate** audio sampling rate (samples/s) * **dmacount** number of linked DMA buffers (optional) * **dmalen** length of each DMA buffer (in samples) (optional) * **apllrate** audio PLL sampling rate (samples/s) (optional) Notes: * **sdin** must be specified for mode = I2S.MASTER_RX * **sdout** must be specified for mode = I2S.MASTER_TX * only **one** of **sdin** or **sdout** can be specified * **apllrate** allows precise specification of the sampling clock rate. **Not needed** for most audio applications. See ESP-IDF docs for usage ## Methods ``` I2S.init(bck, ...) ``` Initialize the I2S peripheral with the given arguments: * see Constructor for argument descriptions *** ``` I2S.deinit() ``` Deinitialize the I2S peripheral *** ``` I2S.readinto(buf, [timeout = -1]) ``` Read audio samples from an I2S peripheral with the given arguments: * **buf** receive buffer. Must support buffer protocol, such as bytearray or array * **timeout** maximum time to wait for a DMA buffer (in ms). If no DMA buffer is available in **timeout** ms the method will return. Default = wait forever to fill buf. When timeout=0 the method will return ***immediately*** if there is no data in DMA memory to copy into the supplied buffer. Timeout=0 can be used to create a non-blocking I2S application with uasyncio. This is shown in the [example code](examples). See discussion below on *Understanding the timeout argument* Notes: * method blocks until buf is *completely* filled from DMA memory, unless timeout is specified * The DMA engine works in the background, filling DMA buffers with audio samples read from the I2S peripheral. The MicroPython runtime is not impacted by this DMA operation. **Returns** number of bytes read *** ``` I2S.write(buf, [timeout = -1]) ``` Write audio samples to an I2S peripheral with the given arguments: * **buf** transmit buffer. Must support buffer protocol, such as bytearray or array * **timeout** maximum time to wait for a DMA buffer (in ms). If no DMA buffer is available in **timeout** ms the function will return. Default = wait forever to write buf. When timeout=0 the method will return ***immediately*** if there is no free DMA memory to copy the transmit buffer. Timeout=0 can be used to create a non-blocking I2S application with uasyncio. This is shown in the [example code](examples). See discussion below on *Understanding the timeout argument* Notes: * method blocks until buf is *completely* copied to DMA memory, unless timeout is specified * The DMA engine works in the background, transfering audio samples from DMA buffers to the I2S peripheral. The MicroPython runtime is not impacted by this DMA operation. **Returns** number of bytes written *** ## Constants **id** of I2S peripheral ``` I2S.NUM0, I2S.NUM1 ``` *** **standard** of I2S peripheral ``` I2S.PHILIPS, I2S.LSB ``` *** **mode** of I2S peripheral ``` I2S.MASTER_RX, I2S.MASTER_TX ``` *** **dataformat** of I2S peripheral ``` I2S.B16, I2S.B24, I2S.B32 ``` *** **channelformat** of I2S peripheral ``` I2S.RIGHT_LEFT, I2S.ALL_RIGHT, I2S.ALL_LEFT, I2S.ONLY_RIGHT, I2S.ONLY_LEFT, ``` See section below "Understanding Channel Format" *** ### ESP32 Development Boards Tested * Adafruit Huzzah Feather ESP32 with external SD card * Lolin D32 Pro * Lolin D32 with external SD card ### I2S Microphone Boards Tested * INMP441 microphone module available on ebay, aliexpress, amazon * MSM261S4030H0 microphone module available on ebay, aliexpress, amazon * Adafruit I2S MEMS Micro