Update i2s.md #303
Update i2s.md #303
Conversation
The documentation was incomplete and vague. I made it better. This still needs a proper tutorial on how to use buffered writes and reads.
|
|
marqdevx
added
fix/update
| - **Frequency = SampleRate x BitsPerChannel x numberOfChannels** | ||
|
|
||
| In a typical setup, the sender of audio data is called a Transmitter and it transfers data to a Receiver at the other end. The device that controls the bus clock, SCK, together with the Word Select - WS - signal is the Controller in the network and in any network just one device can be Controller at any given time; all the other devices connected are in Peripheral mode. The Controller can be the Transmitter, or the Receiver, or a standalone controller. The digitized audio data sample can have a size ranging from 4 bits up to 32. | ||
| The left and right channels are interleaved in the data stream, and "one sample" is one value for the left channel and one for the right. This means that the FS line oscillates at the sample rate. |
There was a problem hiding this comment.
I think this is not 100% needed, could you elaborate this paragraph more maybe?
There was a problem hiding this comment.
The comment about the FS line is valid only for 2 channels, so scratch that. The rest is exposition about the I2S protocol, and that can also be scrapped, although documentation on the I2S protocol is generally hard to find and difficult to read. This is generic documentation, not a more narrowly focused "howto", and I like to educate people. (Work related habit, do as you like.)
|
|
||
| #### Description | ||
| Get the number of bytes available for reading from the I2S interface. This is data that has already arrived and was stored in the I2S receive buffer. available() inherits from the Stream utility class. | ||
| Get the number of **bytes** (not the number of samples) available for reading from the I2S interface. This is data that has already arrived and was stored in the I2S receive buffer. available() inherits from the Stream utility class. |
There was a problem hiding this comment.
On the contrary, my experience is that the most common trap people fall into is to confuse the number of bytes with the number of samples for these functions. This is based on a study of only two test subjects, me and my colleague, but I think it is motivated to point this out. Do as you like.
| The single argument function `write(val)` writes one sample for one channel. A full write requires | ||
| calling this function twice, once for the left channel and once for the right channel. | ||
| If the device buffer is full, the function blocks until the data can be written. | ||
| Before writing, the value `val` will be converted to the appropriate number of bits per sample. |
There was a problem hiding this comment.
It should be n times depending on the amount of channels, if you are only working with one channel then its only once.
There was a problem hiding this comment.
My bad. I have never worked with mono or multi-channel devices.
| The two-argument function `write(buf, len)` writes a sequence of samples from the array `buf`. | ||
| Data must be stored in the proper format for the sample size, with the left and right channels | ||
| interleaved, and the argument `len` specifies the number of **bytes** in the buffer, not the | ||
| number of samples. If the device buffer is too full to hold all the data, the function writes | ||
| as much as will fit (possibly nothing), and returns without blocking. The return value is the | ||
| number of bytes that was actually written. It is the responsibility of the application to | ||
| handle any such partial writes and act accordingly. |
There was a problem hiding this comment.
Be more generic, always referring to the 2 channel scenario
| val: a value to send as a single sample | ||
|
|
||
| buf: an array to send as a series of samples | ||
| buf: an array to send as a sequence of samples |
There was a problem hiding this comment.
In digital signal processing, the correct term is "sequence" of samples. In mathematics, a "series" is something different. There is no real risk of confusion here, but "sequence" is the term I would strongly recommend.
| val = I2S.read() // Might block until data is available for reading | ||
| I2S.read(buf, len) // Will not block, but might not read all the data |
There was a problem hiding this comment.
| val = I2S.read() // Might block until data is available for reading | |
| I2S.read(buf, len) // Will not block, but might not read all the data | |
| int val = I2S.read(); // Might block until data is available for reading | |
| int bufferVal = I2S.read(buf, len); // Will not block, but might not read all the data |
There was a problem hiding this comment.
Yes, of course. Sorry. I'm unfamiliar with the format for this documentation.
|
|
||
| buf: an array to store a sequence of samples | ||
|
|
||
| len: the length of the `buf` array, in bytes (not in number of samples) |
There was a problem hiding this comment.
Remove the content of the parenthesis
There was a problem hiding this comment.
If not mentioned here, definitely deserves pointing out elsewhere. Common pitfall.
|
|
||
| buf: an array to store a sequence of samples | ||
|
|
||
| len: the length of the `buf` array, in bytes (not in number of samples) |
There was a problem hiding this comment.
| len: the length of the `buf` array, in bytes (not in number of samples) | |
| len: the length of the `buf` array, in bytes |
| len: the length of the `buf` array, in bytes (not in number of samples) | ||
|
|
||
| #### Returns | ||
| size_t |
There was a problem hiding this comment.
it does return an int, isn't it?
There was a problem hiding this comment.
Looking at the source, it actually does. It should return a size_t, reasonably, but it doesn't.
|
|
||
| #### Description | ||
| Registers a function to be called when a block of data has been received. | ||
| Registers a function to be called when a block of data has been received. This works just like the `onTransmit()` handler, but for the `read(buf, len)` function that receives data from a device. The callback is not triggered for the no-argument version of `read()` that reads a single sample value. |
There was a problem hiding this comment.
As mentioned before send us the source of this please! 😄
There was a problem hiding this comment.
This was verified by my own experiments. I don't see it mentioned anywhere in the docs, and this was a major headache for me. The fact that the loop() function executes at the sample rate would also be worth mentioning. It's not explicitly stated anywhere in the current docs.
|
Thanks for the replies, I will check them out. 😄 Also maybe you should think on creating a tutorial based on your project if you want. This article is more a library reference than a tutorial, it was taken from old documentation. :) |
|
I will certainly consider writing a "proper" tutorial, although I have a very limited selection of hardware available to me: just the one stereo amplifier and one Arduino board with an on-board microphone. This was just a quick fix for other people to hopefully be able to dodge some of the pitfalls I encountered. |
|
Sounds good! |
|
I am currently experimenting with an Arduino Nano 33 IoT and a 98357 stereo
amplifier. Very low cost and small size, but still very decent sound
quality if you use a decent loudspeaker. My current project is a full
custom Star Wars light saber with purely procedural sound synthesis (no
canned samplings) and a more vividly animated RGB LED strip blade than what
the current commercial controllers offer. It will of course be a lot less
configurable and require reprogramming to change how the thing looks and
sounds and feels. I'm not even going to try to write a user interface for
configuring it.
|
|
Closing the PR due to no changes Please feel free to re-open it to do the changes |
|
Sorry I dropped the ball on this, but I was hit with Covid-19, and I am now
suffering from post-viral brain fatigue. I will need to leave this, and
several other spare time activities, by the wayside until I regain at least
some of my former energy.
|
What This PR Changes
The documentation was incomplete and vague. I made it better.
This still needs a proper tutorial on how to use buffered writes and reads.
Contribution Guidelines