Merge pull request #71 from marcel-licence/update_documentation

Create teensy.md

Author: marcel-licence

extras/audio.md

@@ -0,0 +1,52 @@
+# Audio Codec Interface with Microcontroller
+
+This project demonstrates how to set up and interface an audio codec with a microcontroller using I2S communication. It covers the necessary signal connections, configuration options, and a test signal mode for validation.
+
+## Getting Started
+
+### Overview of Audio Codec Signals
+
+When interfacing an audio codec with a microcontroller, several key signals are involved:
+
+- **BCLK (Bit Clock)**: This is the clock signal that synchronizes the data transfer between the microcontroller and the codec. It defines the speed at which bits are transferred.
+- **WCLK (Word Clock) / LRCLK (Left-Right Clock)**: This signal specifies the sample rate and is used to separate left and right audio channels.
+- **DIN (Data In)**: The data input pin on the codec, where audio data is received from the microcontroller.
+- **DOUT (Data Out)**: The data output pin on the microcontroller, where audio data is sent to the codec.
+
+The microcontroller must be configured to use I2S for these signals, ensuring the codec receives the audio data correctly.
+
+### Configuration
+
+The configuration options for this project are specified in `config.h`. Important parameters include:
+
+- **`SAMPLE_RATE`**: Defines the audio sampling rate.
+- **`SAMPLE_BUFFER_SIZE`**: Determines the buffer size for audio data. This impacts the generated test frequency if enabled.
+
+To test your setup, you can enable a saw wave test signal by defining `OUTPUT_SAW_TEST` in `config.h`. This test signal will output a saw wave with a frequency calculated as:
+
+```c
+Frequency = SAMPLE_RATE / SAMPLE_BUFFER_SIZE
+```
+
+Example:
+```c
+#define OUTPUT_SAW_TEST  // Uncomment to enable the saw wave test signal
+```
+
+### Codec-Specific Considerations
+
+Some codecs may require additional configuration:
+
+- **I2S Configuration**: Most audio codecs can be configured over I2S. Ensure that your microcontroller's I2S settings (bit depth, sample rate, etc.) are compatible with the codec's specifications.
+- **Additional Pins**: Certain codecs, such as the PCM5201a, may have additional pins like a *Mute* pin. Refer to the codec-specific documentation [PCM5102a](ml_pcm5102a.md) for details on these configurations.
+
+### Running the Project
+
+1. **Flash the Firmware**: Program the microcontroller with the provided firmware.
+2. **Check Serial Monitor**: After starting the firmware, open the serial monitor. The monitor will display the pin settings for the I2S interface, allowing you to verify correct signal connections and configuration.
+
+## Contributing and Support
+
+For questions, feedback, or further assistance, feel free to start a discussion on the GitHub repository.
+
+Happy coding!

extras/teensy.md

@@ -0,0 +1,75 @@
+# ML_SynthTools Library with Teensy
+
+This guide explains how to use the `ML_SynthTools` library with the Teensy board, including necessary modifications to ensure proper functionality. Follow the steps below to integrate and configure everything correctly.
+
+## Required Changes to Teensy Setup
+
+To use `ML_SynthTools` with the Teensy, there are a few modifications that need to be made to the Teensy core files. These changes adjust linker flags and audio settings for compatibility with your library.
+
+### 1. Add Linker Flags to `platform.txt`
+
+To configure the correct linker flags, you need to modify the `platform.txt` file for Teensy. This ensures that the necessary libraries are linked correctly.
+
+- Locate the `platform.txt` file in the following directory:
+  ```
+  %appdata%\..\Local\Arduino15\packages\teensy\hardware\avr\1.59.0\platform.txt
+  ```
+
+- Open the file in a text editor, and add the following line under the section for `compiler.libraries.ldflags`:
+  ```
+  compiler.libraries.ldflags=
+  ```
+
+This will enable the necessary linker flags required by `ML_SynthTools`.
+
+### 2. Modify Audio Stream Header for Block Size and Sample Rate
+
+Next, you need to update some audio settings in the Teensy core to ensure compatibility with the `ML_SynthTools` library.
+
+- Navigate to the following Teensy file:
+  ```
+  %appdata%\..\Local\Arduino15\packages\teensy\hardware\avr\1.59.0\cores\teensy4\AudioStream.h
+  ```
+
+- Open the file and locate the line:
+  ``` c
+  #define AUDIO_BLOCK_SAMPLES  128
+  ```
+
+- Change it to:
+  ``` c
+  #define AUDIO_BLOCK_SAMPLES  48
+  ```
+
+  This modification adjusts the number of audio samples in each audio block for better performance with the `ML_SynthTools` library.
+
+- Next, find the line:
+  ``` c
+  #define AUDIO_SAMPLE_RATE_EXACT 44100.0f
+  ```
+
+- Change it to:
+  ``` c
+  #define AUDIO_SAMPLE_RATE_EXACT 48000.0f
+  ```
+
+  This sets the audio sample rate to 48 kHz, which is required for the correct operation of `ML_SynthTools`.
+
+## Installation Steps
+
+1. **Install Teensyduino:** If you haven't already, make sure to install [Teensyduino](https://www.pjrc.com/teensy/teensyduino.html), which provides the necessary libraries and tools for programming the Teensy board.
+
+2. **Install `ML_SynthTools` Library:**  
+   - Download or clone the `ML_SynthTools` library to your Arduino libraries folder.
+   - You can also install it via the Arduino Library Manager (if available).
+
+3. **Configure the Teensy Board:**  
+   - In the Arduino IDE, go to **Tools** > **Board** and select your Teensy model.
+   - Set the correct COM port for the Teensy.
+
+4. **Upload Your Code:**  
+   - Once the above steps are completed, upload your code that uses the `ML_SynthTools` library to your Teensy board.
+
+## Conclusion
+
+After making these changes, you should be able to use the `ML_SynthTools` library with your Teensy board. If you encounter any issues, make sure all modifications are correctly applied and that the Teensy board is properly selected in the Arduino IDE.