[FEATURE] Basic implementation of Arduino's I2S library

[PilnyTomas]

Basic version of Arduino's I2S library. We currently support only 16bps + 16000 Hz sampling frequency. Other bitrates and sample rates will print warning and continue to operate, however the resulting audio quality may be poor.
There will be further effort to fix these issues.

Tasks lists:

• Upload to GitHub 1st version of I2S Library PR
• Fix and specify basic functions of I2S Library
• Verify thread safety
• Fix CI errors
• Auto config of ADC for selecting different pins. Done
  • Implement GPIO to ADC unit & channel conversion methods in IDF i2s driver + edit Arduino I2S acordingly (Will be implemented by responsible team)
• create a workaround about sample rate limitations
• waiting review (consider configuration with Sample rate) @SuGlider
• Implementing proposed changes of @SuGlider by @tomaspilny
• evaluate EVENTS calls (ESP-IDF)

[CLAassistant]

All committers have signed the CLA.

[PilnyTomas]

Commit f366160 improved performance by implementing internall buffer. This buffer is usefull especially when using single-byte writes and reads.
Input should be generally ok, however when reading silent channel I'm getting value 1, but I would expect value 0. I'm not sure if it is expected in ESP, but Arduino has 0 value for silent channel.
Output is little distorted, but much better than without the buffer. I will try using queue instead of buffer and see if it improves performance further.

[SuGlider]

Commit f366160 improved performance by implementing internall buffer. This buffer is usefull especially when using single-byte writes and reads.

--Buffering helps in storing data using single-byte operations. But what happens, during single write, when the sketch is faster in producing than the I2S in consuming? Will it overwrite data, for instance? Would this explain output distortion?

---

Output is little distorted, but much better than without the buffer. I will try using queue instead of buffer and see if it improves performance further.

-- It may help, as commented above about a potential racing condition. Another way to improve it would be the usual "whole sample array" being sent at once to I2S Write().

[SuGlider]

Instead of using Serial.print() in the I2S.cpp, or as in the places removed in the PR, I'd suggest to use ESP_LOGx(...) instead. Please look at https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-log.h

I think i2s_write() and i2s_read are already thread safe (based on the code of i2c.c in IDF driver). Thus, maybe, the use of another MUTEX in I2SClass::read() and I2SClass::write() may be redundant. Please check it.

Examples that use single sample Write/Read may produce a racing condition with possible internal buffer overwrite, for instance. For instance, continuous writing in loop() may be faster than I2S data consumption. It may need to use Queues in sigle sample mode or Interrupts with full sample array usage.

[PilnyTomas]

--Buffering helps in storing data using single-byte operations. But what happens, during single write, when the sketch is faster in producing than the I2S in consuming? Will it overwrite data, for instance? Would this explain output distortion?

Yes, it might explain the distortion.

-- It may help, as commented above about a potential racing condition. Another way to improve it would be the usual "whole sample array" being sent at once to I2S Write().

Yes, filling the buffer and then writing it would be faster, but I'm trying to implement it in compliance with the original Arduino examples which generate and write (or read and print) samples one-by-one, see the examples in original Arduino library

Instead of using Serial.print() in the I2S.cpp, or as in the places removed in the PR, I'd suggest to use ESP_LOGx(...) instead. Please look at https://github.com/espressif/arduino-esp32/blob/master/cores/esp32/esp32-hal-log.h

Thanks for the tip. I was going to do that in near future :)

I think i2s_write() and i2s_read are already thread-safe (based on the code of i2c.c in IDF driver). Thus, maybe, the use of another MUTEX in I2SClass::read() and I2SClass::write() may be redundant. Please check it.

Mutex is not for the read/write, but for the buffers.

Examples that use single sample Write/Read may produce a racing condition with possible internal buffer overwrite, for instance. For instance, continuous writing in the loop() may be faster than I2S data consumption. It may need to use Queues in single sample mode or Interrupts with full sample array usage.

Yes, you are right, thank you, I did not realize this when I was writing it. In the current implementation the write function will simply refuse to write into the buffer (and return 0 Bytes written) and the samples will be lost.

[SuGlider]

Approved as is, for the community's valuation.
Future revisions will be necessary.

[VojtechBartoska]

@pedrominatel Can you please help with review of initial I2S Documentation here?