From 1d525cc80430f06de9d79f14d611f09db2f00732 Mon Sep 17 00:00:00 2001
From: iabdalkader <i.abdalkader@gmail.com>
Date: Thu, 28 Mar 2024 16:11:18 +0100
Subject: [PATCH] docs: Document API changes and new classes.

Signed-off-by: iabdalkader <i.abdalkader@gmail.com>
---
 docs/api.md    | 405 ++++++++++++++++++++++++++++++++++++-------------
 docs/readme.md |  50 ++++--
 2 files changed, 343 insertions(+), 112 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 7d4e444..11ef7f4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -4,7 +4,7 @@
 
 ### `AdvancedADC`
 
-Creates an object associated to a specific pin.
+Creates an ADC object using the specified pin(s). The ADC object can sample a single channel or multiple channels successively if more than one pin is passed to the constructor. In this case, data from multiple channels will be interleaved in sample buffers. Additionally, the ADC channel of the first pin determines the ADC instance used, and the remaining channels (if any) must all belong to the same ADC instance.
 
 #### Syntax
 
@@ -14,18 +14,15 @@ AdvancedADC adc(analogPin);
 
 #### Parameters
 
-- Pin `A0` through `A11` can be associated.
+- Pin `A0` through `A11` can be used.
 
 #### Returns
 
-Nothing.
+`void`.
 
 ### `begin()`
 
-
-Initializes the ADC with the specific parameters. The `begin()` method is firstly used to initialize the library.
-
-If reconfigured during program execution, use `stop()` first.
+Initializes and configures the ADC with the specified parameters. To reconfigure the ADC, `stop()` must be called first.
 
 #### Syntax
 
@@ -35,15 +32,25 @@ adc0.begin(resolution, sample_rate, n_samples, n_buffers)
 
 #### Parameters
 
-- `enum` - analog read resolution (choose from 8, 10, 12, 14, 16 bit).
+- `enum` - **resolution** the sampling resolution (can be 8, 10, 12, 14 or 16 bits).
   - `AN_RESOLUTION_8`
   - `AN_RESOLUTION_10`
   - `AN_RESOLUTION_12`
   - `AN_RESOLUTION_14`
   - `AN_RESOLUTION_16`
-- `int` - **sample_rate** - the sample rate / frequency in Hertz, e.g. `16000`.
-- `int` - **n_samples** - number of samples we want to acquire, e.g. `32`. When reading the ADC, we store these samples into a specific buffer (see [SampleBuffer](#samplebuffer)), and read them via `buffer[x]`, where `x` is the sample you want to retrieve.
-- `int` - **n_buffers** - the number of buffers in the queue.
+- `int` - **sample_rate** - the sampling rate / frequency in Hertz, e.g. `16000`.
+- `int` - **n_samples** - the number of samples per sample buffer. See [SampleBuffer](#samplebuffer) for more details.
+- `int` - **n_buffers** - the number of sample buffers in the queue. See [SampleBuffer](#samplebuffer) for more details.
+- `bool` - **start** - if true (the default) the ADC will start sampling immediately, otherwise `start()` can be called later to start the ADC.
+- `enum` - **sample_time** - the sampling time in cycles (the default is 8.5 cycles).
+  - `AN_ADC_SAMPLETIME_1_5`
+  - `AN_ADC_SAMPLETIME_2_5`
+  - `AN_ADC_SAMPLETIME_8_5`
+  - `AN_ADC_SAMPLETIME_16_5`
+  - `AN_ADC_SAMPLETIME_32_5`
+  - `AN_ADC_SAMPLETIME_64_5`
+  - `AN_ADC_SAMPLETIME_387_5`
+  - `AN_ADC_SAMPLETIME_810_5`
 
 #### Returns
 
@@ -51,7 +58,7 @@ adc0.begin(resolution, sample_rate, n_samples, n_buffers)
 
 ### `available()`
 
-Bool to check if there's any available data on the ADC channel.
+Checks if the ADC is readable.
 
 #### Syntax
 
@@ -65,15 +72,29 @@ None.
 
 #### Returns
 
-1 on success, 0 on failure.
+Returns true, if there's at least one sample buffer in the read queue, otherwise returns false.
 
 ### `read()`
 
-Reads the first available byte in the buffer.
+Returns a sample buffer from the queue for reading.
+
+### `start()`
+
+Starts the ADC sampling.
+
+#### Syntax
+
+```
+adc.start()
+```
+
+#### Returns
+
+1 on success, 0 on failure.
 
 ### `stop()`
 
-Stops the ADC and buffer transfer, and releases any memory allocated for the buffer array.
+Stops the ADC and releases all of its resources.
 
 #### Syntax
 
@@ -85,12 +106,71 @@ adc.stop()
 
 - `1`
 
+## AdvancedADCDual
+
+### `AdvancedADCDual`
+
+The AdvancedADCDual class enables the configuration of two ADCs in Dual ADC mode. In this mode, the two ADCs are synchronized, and can be sampled simultaneously, with one ADC acting as the master ADC. Note: This mode is only supported on ADC1 and ADC2, and they must be passed to `begin()` in that order.
+
+#### Syntax
+
+```
+AdvancedADCDual adc_dual(adc1, adc2);
+```
+
+#### Parameters
+
+- `AdvancedADC` - **adc1** - the first ADC (must be ADC1).
+- `AdvancedADC` - **adc2** - the second ADC (must be ADC2).
+
+#### Returns
+
+`void`.
+
+### `begin()`
+
+Initializes and starts the two ADCs with the specified parameters.
+
+#### Syntax
+
+```
+adc_dual.begin(resolution, sample_rate, n_samples, n_buffers)
+```
+
+#### Parameters
+
+- `enum` - **resolution** the sampling resolution (can be 8, 10, 12, 14 or 16 bits).
+  - `AN_RESOLUTION_8`
+  - `AN_RESOLUTION_10`
+  - `AN_RESOLUTION_12`
+  - `AN_RESOLUTION_14`
+  - `AN_RESOLUTION_16`
+- `int` - **sample_rate** - the sampling rate / frequency in Hertz, e.g. `16000`.
+- `int` - **n_samples** - the number of samples per sample buffer. See [SampleBuffer](#samplebuffer) for more details.
+- `int` - **n_buffers** - the number of sample buffers in the queue. See [SampleBuffer](#samplebuffer) for more details.
+- `enum` - **sample_time** - the sampling time in cycles (the default is 8.5 cycles).
+  - `AN_ADC_SAMPLETIME_1_5`
+  - `AN_ADC_SAMPLETIME_2_5`
+  - `AN_ADC_SAMPLETIME_8_5`
+  - `AN_ADC_SAMPLETIME_16_5`
+  - `AN_ADC_SAMPLETIME_32_5`
+  - `AN_ADC_SAMPLETIME_64_5`
+  - `AN_ADC_SAMPLETIME_387_5`
+  - `AN_ADC_SAMPLETIME_810_5`
+
+#### Returns
+
+1 on success, 0 on failure.
+
+### `stop()`
+
+Stops the dual ADCs and releases all resources.
+
 ## AdvancedDAC
 
 ### `AdvancedDAC`
 
-
-Creates a DAC object on a specific pin.
+Creates a DAC object using the specified pin.
 
 #### Syntax
 
@@ -105,31 +185,27 @@ AdvancedDAC dac1(A13);
 
 #### Returns
 
-Nothing.
+`void`.
 
 ### `begin()`
 
-
-Initializes the DAC with the specific parameters. The `begin()` method is firstly used to initialize the library.
-
-If reconfigured during program execution, use `stop()` first.
+Initializes the DAC with the specified parameters. To reconfigure the DAC, `stop()` must be called first.
 
 #### Syntax
 
 ```
-dac0.begin(resolution, frequency, n_samples, n_buffers)
+dac.begin(resolution, frequency, n_samples, n_buffers)
 ```
 
 #### Parameters
 
-- `enum` - resolution (choose from 8, 10, 12 bit)
+- `enum` - resolution (can be 8, 10, 12 bits).
   - `AN_RESOLUTION_8`
   - `AN_RESOLUTION_10`
   - `AN_RESOLUTION_12`
-- `int` - **frequency** - the frequency in Hertz, e.g. `8000`.
-- `int` - **n_samples** - number of samples we want to write, e.g. `32`. When writing to the DAC, we first write the samples into a buffer (see [SampleBuffer](#samplebuffer)), and write it to the DAC using `dac_out.write(buf)`.
-- `int` - **n_buffers** - the number of buffers in the queue.
-
+- `int` - **frequency** - the output frequency in Hertz, e.g. `8000`.
+- `int` - **n_samples** - the number of samples per sample buffer. See [SampleBuffer](#samplebuffer) for more details.
+- `int` - **n_buffers** - the number of sample buffers in the queue. See [SampleBuffer](#samplebuffer) for more details.
 
 #### Returns
 
@@ -137,7 +213,7 @@ dac0.begin(resolution, frequency, n_samples, n_buffers)
 
 ### `available()`
 
-Checks if the DAC channel is available to write to.
+Checks if the DAC is writable.
 
 #### Syntax
 
@@ -151,13 +227,11 @@ None.
 
 #### Returns
 
-1 on success, 0 on failure.
-
+Returns true, if there's at least one free sample buffer in the write queue, otherwise returns false.
 
 ### `dequeue()`
 
-
-Creates a buffer object and waits until a buffer to become available.
+Returns a sample buffer from the queue for writing. 
 
 #### Syntax
 
@@ -165,7 +239,7 @@ Creates a buffer object and waits until a buffer to become available.
 SampleBuffer buf = dac.dequeue();
 
 for (size_t i=0; i<buf.size(); i++) {
-     buf[i] =  SAMPLES_BUFFER[i];
+    buf[i] =  SAMPLES_BUFFER[i];
 }
 
 dac1.write(buf);
@@ -173,8 +247,7 @@ dac1.write(buf);
 
 ### `write()`
 
-
-Writes the buffer to the DAC channel specified. Before writing, the cached data is flushed.
+Writes the sample buffer back to the DAC.
 
 #### Syntax
 
@@ -184,11 +257,11 @@ dac1.write(buf);
 
 #### Parameters
 
-- A buffer containing the samples (see [SampleBuffer](#samplebuffer)).
+- A sample buffer. See [SampleBuffer](#samplebuffer) for more details.
 
 ### `stop()`
 
-Stops the DAC timer and buffer transfer, and releases any memory allocated for the buffer array.
+Stops the DAC and releases all of its resources.
 
 #### Syntax
 
@@ -202,7 +275,7 @@ dac.stop()
 
 ### `frequency()`
 
-Sets the frequency for the DAC. This can only be used after `begin()`, where an initial frequency is set.
+Sets the DAC's frequency. This function can only be used after `begin()` has been called.
 
 #### Syntax
 
@@ -216,19 +289,180 @@ dac.frequency(frequency);
 
 - `int` - frequency in Hertz (Hz).
 
+## AdvancedI2S
+
+### `AdvancedI2S`
+
+Creates an I2S object using the specified pins. The I2S object can be configured in input, output or full-duplex (in/out) modes to read/write PCM samples.
+
+#### Syntax
+
+```
+AdvancedI2S i2s(WS, CK, SDI, SDO, MCK);
+```
+
+#### Parameters
+
+- `WS` I2S word select (LR clock).
+- `CK` I2S bit-clock (BRCLK clock).
+- `SDI` I2S data input (can be `NC` in half-duplex output mode).
+- `SDO` I2S data output (can be `NC` in half-duplex input mode).
+- `MCK` Master clock (can be `NC` if no MCLK is required).
+
+#### Returns
 
+`void`.
+
+### `begin()`
+
+Initializes and starts the I2S device.
+
+#### Syntax
+
+```
+i2s.begin(mode, resolution, frequency, n_samples, n_buffers)
+```
+
+#### Parameters
+
+- `enum` - **mode** - The I2S mode.
+  - `AN_I2S_MODE_IN`
+  - `AN_I2S_MODE_OUT`
+  - `AN_I2S_MODE_INOUT`
+- `int` - **sample_rate** - The sample rate / frequency in Hertz, e.g. `16000`.
+- `int` - **n_samples** - the number of samples per sample buffer. See [SampleBuffer](#samplebuffer) for more details.
+- `int` - **n_buffers** - the number of sample buffers in the queue. See [SampleBuffer](#samplebuffer) for more details.
+
+#### Returns
+
+1 on success, 0 on failure.
+
+### `available()`
+
+Checks if the I2S is readable, writable or both (in full-duplex mode).
+
+#### Syntax
+
+```
+if(i2s.available()){}
+```
+
+#### Parameters
+
+None.
+
+#### Returns
+
+Returns true if I2S is readable, writable or both (in full-duplex mode), false if not.
+
+### `read()`
+
+Returns a sample buffer from the queue for reading. This function can be called in half-duplex input or full-duplex modes. When the buffer is no longer needed, it should be returned to I2S by calling `release()`, see [SampleBuffer](#release) for more details.
+
+#### Syntax
+
+```
+SampleBuffer buf = i2s.read();
+
+for (size_t i=0; i<buf.size(); i++) {
+    Serial.println(buf[i]);
+}
+
+i2s.release(buf);
+```
+
+### `dequeue()`
+
+Returns a sample buffer from the queue for writing. This function can be called in half-duplex output or full-duplex modes. When the buffer is done, it can be added to the I2S write queue by calling `write()` (see [I2S](#write))
+
+#### Syntax
+
+```
+SampleBuffer buf = i2s.dequeue();
+
+for (size_t i=0; i<buf.size(); i++) {
+    buf[i] =  SAMPLES_BUFFER[i];
+}
+
+i2s.write(buf);
+```
+
+### `write()`
+
+Writes a sample buffer to I2S.
+
+#### Syntax
+
+```
+i2s.write(buf);
+```
+
+#### Parameters
+
+- A buffer containing the samples (see [SampleBuffer](#samplebuffer)).
+
+### `stop()`
+
+Stops the I2S and releases all of its resources.
+
+#### Syntax
+
+```
+i2s.stop()
+```
+
+#### Returns
+
+- `1`
+
+## WavReader
+
+### `WavReader`
+
+Creates a WAV file reader.
+
+### `begin()`
+
+Initializes the WAV reader, opens the WAV file and reads the WAV header.
+
+#### Syntax
+
+```
+wav.begin(path, n_samples, n_buffers, loop)
+```
+
+#### Parameters
+
+- `string` - **path** - the path to the WAV file.
+- `int` - **n_samples** - the number of samples per sample buffer. See [SampleBuffer](#samplebuffer) for more details.
+- `int` - **n_buffers** - the number of sample buffers in the queue. See [SampleBuffer](#samplebuffer) for more details.
+- `bool` - **loop* - if true, the WAV reader will loop back to the start of the file, when the end file is reached.
+
+### `stop()`
+
+Stops the WAV file and releases all of its resources (include the WAV file handle).
+
+### `available()`
+
+Returns true if the WAV file has more data to be read.
+
+### `read()`
+
+Returns a sample buffer from the queue for reading.
+
+### `rewind()`
+
+If `loop` is false, this functions restarts the file read position.
 
 ## SampleBuffer
 
 ### Sample
 
-`Sample` is the data type used for the [`SampleBuffer`](#samplebuffer-1), and is identical to an unsigned short variable (`uint16_t`).
-
-A single `Sample` can store 2^16 or 65,535 distinct values.
+Represents a single data item in a [`SampleBuffer`](#samplebuffer-1). The `Sample` type is pre-defined by the library as an unsigned short (`uint16_t`) type.
 
 ### `SampleBuffer`
 
-`SampleBuffer` is used to store samples (see [Sample](#sample)) that are then written to the DAC. Before writing, first use `dequeue()`, then write data to the buffer.
+Sample buffer objects are used throughout the library to store data samples for reading or writing. They can be used directly by the DMA, as they're cache-line-aligned, and their cache coherency is maintained by the library. The memory for sample buffers is allocated internally from memory pools and managed by the library. Each sample buffer belongs to a single memory pool, from which it was allocated, and the memory pool assigns it to the read or write queue.
 
 #### Syntax
 
@@ -236,7 +470,7 @@ A single `Sample` can store 2^16 or 65,535 distinct values.
 SampleBuffer buf = dac.dequeue();
 
 for (size_t i=0; i<buf.size(); i++) {
-     buf[i] =  SAMPLES_BUFFER[i];
+    buf[i] =  SAMPLES_BUFFER[i];
 }
 
 dac1.write(buf);
@@ -244,7 +478,7 @@ dac1.write(buf);
 
 ### `data()`
 
-Returns a pointer to the buffer's memory. 
+Returns a pointer to the buffer's internal memory. The buffer's internal memory is contiguous and can be used with memcpy, for example.
 
 ```
 buf.data()
@@ -252,15 +486,19 @@ buf.data()
 
 ### `size()`
 
-Returns the size of the buffer.
+Returns the buffer size in samples (i.e., the number of samples in the buffer).
 
 ```
 buf.size()
 ```
 
+#### Returns
+
+- The buffer size in samples.
+
 ### `bytes()`
 
-Returns the total number of bytes used to store the audio data, by using the formula `n_samples * n_channels * sample`.
+Returns the buffer size in bytes (i.e., the `number of samples * number of channels * sample size`).
 
 ```
 buf.bytes()
@@ -268,11 +506,11 @@ buf.bytes()
 
 #### Returns
 
-- Total number of bytes.
+- The buffer size in bytes.
 
 ### `flush()`
 
-Clears the data cache.
+Flushes any cached data for the buffer.
 
 ```
 buf.flush()
@@ -280,7 +518,7 @@ buf.flush()
 
 ### `invalidate()`
 
-Invalidats the cache by discarding the data.
+Invalidats any cached data for the buffer.
 
 ```
 buf.invalidate()
@@ -300,7 +538,7 @@ buf.timestamp()
 
 ### `channels()`
 
-Returns the number of channels used in the buffer.
+Returns the number of channels in the buffer.
 
 ```
 buf.channels()
@@ -313,7 +551,7 @@ buf.channels()
 
 ### `release()`
 
-Releases the buffer back into a free pool.
+Releases the buffer back to its memory pool.
 
 ```
 buf.release()
@@ -321,84 +559,45 @@ buf.release()
 
 #### Returns
 
-- Nothing (void).
+`void`.
 
 ### `setflags()`
 
-Sets flag(s) for the buffer. 
+This function is used internally by the library to set the buffer's flags. The flags can be one or both of two options: `DMA_BUFFER_DISCONT` set if the capture was stopped and then restarted, and `DMA_BUFFER_INTRLVD` which indicates that the data in the buffer is interleaved.
 
 ```
-buf.setflags(int arg)
+buf.setflags(uint32_t mask)
 ```
 
 ### `getflags()`
 
-Get flag(s) of the buffer.
+Returns true if any of the buffer flags specified in the mask argument is set. The flags can be one or both of two options: `DMA_BUFFER_DISCONT` set if the capture was stopped and then restarted, and `DMA_BUFFER_INTRLVD` which indicates that the data in the buffer is interleaved.
 
-```
-buf.getflags(int arg)
-```
-
-#### Returns
-
-- `int` - flags.
-
-### `clrflags()`
-
-Clear flag(s) from the buffer.
 
 ```
-buf.getflags(int arg)
-```
-
-### `writable()`
-
-Returns the amount of writable elements in the buffer.
-
-```
-buf.writable()
+buf.getflags(uint32_t mask)
 ```
 
 #### Returns
 
-- Amount of readable elements in the buffer.
+Returns true if any of the buffer flags specified in the mask argument is set, otherwise returns false.
 
-### `readable()`
+### `clrflags(uin32_t mask)`
 
-Returns the amount of readable elements in the buffer.
+Clears the buffer flags specified in the mask argument.
 
 ```
-buf.readable()
+buf.clrflags(uint32_t mask)
 ```
 
-### `allocate()`
+#### Returns
 
-Used to obtain a buffer from the free queue. 
-
-```
-buf.allocate()
-```
+`void`.
 
 ### `release()`
 
-Releases the buffer back to the free queue.
+Releases the buffer back to its memory pool.
 
 ```
 buf.release()
 ```
-
-### `enqueue()`
-
-Add a DMA buffer to the ready queue.
-
-```
-buf.enqueue()
-```
-
-### `dequeue()`
-
-Return a DMA buffer from the ready queue.
-
-```
-buf.dequeue()
-```
\ No newline at end of file
diff --git a/docs/readme.md b/docs/readme.md
index 031ec2f..246c437 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -1,18 +1,21 @@
-# Arduino_AdvancedAnalog library
+# Arduino Advanced Analog Library
 
 [![License](https://img.shields.io/badge/License-LGPLv2.1-blue.svg)](../LICENSE)
 
-The **Arduino_AdvancedAnalog** library is designed to offer high performance DAC/ADC applications on boards based on the STM32H747XI microcontroller:
+The Arduino Advanced Analog library enables high performance DAC, ADC and I2S applications on boards based on the STM32H7 microcontrollers:
 - [Arduino GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi)
 - [Arduino Portenta H7](https://store.arduino.cc/products/portenta-h7)
 
 ## Features
 
-- ADC/DAC parameters fine tuning: resolution, channel number, queue number and size
-- ADC acquisition with DMA in double buffering mode
-- ADC Multichannel acquisition
-- DAC Multichannel writing 
-- Storing ADC samples history in multiple queues
+- Efficient memory management using DMA buffer pools.
+- Configurable sample rate, sampling time, resolution, and number of channels.
+- Samples are stored in dynamically configurable queues.
+- ADC multi-channel acquisition and dual mode support.
+- I2S input, output, and full-duplex mode support.
+- All drivers utilize DMA in double buffer mode.
+- A WAV file reader that supports loop mode.
+
 ## Guides
 
 To learn more about using the DAC & ADC on the GIGA R1 WiFi, check out the [GIGA Advanced DAC/ADC Guide](https://docs.arduino.cc/tutorials/giga-r1-wifi/giga-audio).
@@ -160,9 +163,38 @@ void loop() {
 }
 ```
 
+### I2S
+
+To use this library for I2S application, you must have a supported Arduino board and include the AdvancedAnalog library in your Arduino sketch. Here is a minimal example for the Arduino GIGA R1 WiFi:
+
+```cpp
+#include <Arduino_AdvancedAnalog.h>
+
+// WS, CK, SDI, SDO, MCK
+AdvancedI2S i2s(PG_10, PG_11, PG_9, PB_5, PC_4);
+
+void setup() {
+    Serial.begin(9600);
+
+    // Resolution, sample rate, number of samples per channel, queue depth.
+    if (!i2s.begin(AN_I2S_MODE_IN, 32000, 512, 32)) {
+        Serial.println("Failed to start I2S");
+        while (1);
+    }
+}
+
+void loop() {
+    if (i2s.available()) {
+      SampleBuffer buf = i2s.read();
+      // process samples.
+      buf.release();
+    }
+}
+```
+
 ## Examples
-- **[Advanced](../examples/Advanced):** This folder contains examples showing how to configure ADC/DAC to read/write data.
-- **[Beginner](../examples/Beginner):** This folder contains examples showing how to generate waveforms with DAC.
+- **[Beginner](../examples/Beginner):** This folder contains full applications, like audio playback and a waveform generator.
+- **[Advanced](../examples/Advanced):** This folder contains more specific examples showing advanced API configurations.
 
 ## API