Merge pull request #535 from arduino/benjamindannegard/display-shield-microphone-update

[Display Shield] microphone update

Author: BenjaminDannegard

content/hardware/10.mega/shields/giga-display-shield/tutorials/07.microphone-tutorial/content.md

@@ -5,105 +5,99 @@ author: Benjamin Dannegård
 tags: [Display, microphone, LVGL]
 ---
 
-The GIGA Display Shield comes equipped with on-board microphone and with the help of LVGL the microphones readings can be visualized on the screen. This tutorial will show you how to create a sketch that ties together the microphones readings with visual elements on the screen.
+
+The GIGA Display Shield comes equipped with on-board microphone that when combined with the visual element of the GIGA Display Screen can be used in a number of ways. For example, using the LVGL framework the display can be used to show an animated volume indicator. Using the [Arduino_Graphics]() or [Arduino_GigaDisplay_GFX](https://github.com/arduino-libraries/Arduino_GigaDisplay_GFX) libraries we can detect when a loud noise, like a clap is made and change a visual element on the screen. This tutorial will take a closer look at the [PDM library](https://docs.arduino.cc/learn/built-in-libraries/pdm) to see how this can be used. And then re-create the two sketches mentioned.
 
 ## Hardware & Software Needed
 
 - [Arduino GIGA R1 WiFi](/hardware/giga-r1)
 - [Arduino GIGA Display Shield](/hardware/giga-display-shield)
 - [Arduino IDE](https://www.arduino.cc/en/software)
-- [LVGL library](https://reference.arduino.cc/reference/en/libraries/lvgl/)
 
 ## Downloading the Library and Core
 
-Make sure the latest GIGA core is installed in the Arduino IDE. **Tools > Board > Board Manager...**. Here you need to look for the **Arduino Mbed OS Giga Boards** and install it, the [Arduino_H7_Video library](https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video) and [PDM library](https://docs.arduino.cc/learn/built-in-libraries/pdm) are included in the core. Now you have to install the library needed for handling the visual component. Go to **Tools > Manage libraries..**, search for **LVGL**, and install it.
+Make sure the latest GIGA core is installed in the Arduino IDE. **Tools > Board > Board Manager...**. Here you need to look for the **Arduino Mbed OS Giga Boards** and install it, the [Arduino_H7_Video library](https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video) and [PDM library](https://docs.arduino.cc/learn/built-in-libraries/pdm) are included in the core.
 
 ## Microphone Readings With The Shield
 
-### Test Microphone
+### Testing The Microphone
 
 To test the microphone we can use the **PDMSerialPlotter** example sketch. This sketch can be found in **File > Examples > PDM** in the Arduino IDE. This sketch will print readings in the serial monitor. Upload the sketch and check so that readings are appearing in the serial monitor.
 
 ![Example sketch printing values in the serial monitor](assets/pdm-test-sketch.png)
 
 ### Using the Microphone Readings
 
-Now let's create a sketch that combines the microphone readings with a visual component. First, the libraries we need are, `PDM.h` which will handle the microphone readings and `lvgl.h` will handle the visual elements on the screen.
+Now let's take a look at the PDM sketch and how we can use the microphone readings.
 
-```arduino
-#include <PDM.h>
-#include "Arduino_H7_Video.h"
-#include "lvgl.h"
-```
-
-In the `setup()` we can start the display with `Display.begin();` and the microphone with `PDM.onReceive(onPDMdata);`. This will call the `void onPDMdata()` function at the bottom of the sketch. This function handles collecting and storing the readings from the microphone.
+First we need to define the number of output channels, output frequency, a variable for counting when reading from the buffer and creating the buffer which the readings will be put into. This is done with the following lines:
 
 ```arduino
-void setup() {
-  Display.begin();
+// default number of output channels
+static const char channels = 1;
 
-  PDM.onReceive(onPDMdata);
+// default PCM output frequency
+static const int frequency = 16000;
 
-  if (!PDM.begin(channels, frequency)) {
-    Serial.println("Failed to start PDM!");
-    while (1);
-  }
-}
+// Buffer to read samples into, each sample is 16-bits
+short sampleBuffer[512];
+
+// Number of audio samples read
+volatile int samplesRead;
 ```
 
-In the `setup()` we will also create our LVGL bar and animation for that bar. Make sure you also define the `lv_obj_t * obj;` and `lv_anim_t a;` variables outside of the `setup()` function so they can be used in the `loop()` function later. Now `obj` will be the name of bar object. These next lines will set the bar's position, size and values. After that we can initialize the animation and set the time for the animation. Then we set the animation to our bar with `lv_anim_set_var(&a, obj);`.
+A callback function needs to be set, which is called when new PDM data is ready to be read. We do this in the `setup()` function using:
 
 ```arduino
-  // Create the bar
-  obj = lv_bar_create(lv_scr_act());
-  lv_obj_set_size(obj, 600, 50);
-  lv_obj_center(obj);
-  lv_bar_set_value(obj, 500, LV_ANIM_OFF);
-  
-  // Create the animation for the bar
-  lv_anim_init(&a);
-  lv_anim_set_exec_cb(&a, set_slider_val);
-  lv_anim_set_time(&a, 300);
-  lv_anim_set_playback_time(&a, 300);
-  lv_anim_set_var(&a, obj);
+  PDM.onReceive(onPDMdata);
 ```
 
-The microphone readings will be put into a buffer, in the `loop()` we will need to go through all the samples in the buffer. We can do this with a simple `for()` loop. If you ran the previous mic test sketch you will know that the readings can get pretty high in value, to make it fit our LVGL component reduce that value. By assigning the value to our `micValue` variable we can make it fit the visual element and easily use it to set the end value of the animation with `lv_anim_set_values(&a, 0, micValue)`.
+`onPDMdata` is the callback function that we will have to create at the end of the sketch.
 
-```arduino
-void loop() {
-  
-  // Wait for samples to be read
-  if (samplesRead) {
+Now when we want to print or use the readings lets do it with a `for` loop since they are inside a buffer, which we need to step through. But lets first check so that there are readings to be printed with a simple `if` statement. These lines will step through the buffer until all the readings inside are printed and then start over:
 
-    // Print samples to the serial monitor or plotter
+```arduino
+if (samplesRead) {
     for (int i = 0; i < samplesRead; i++) {
       Serial.println(sampleBuffer[i]);
-      micValue = sampleBuffer[i];
-      micValue = micValue / 100;
-      if (micValue > 500)
-      {
-        micValue = 500;
-      }
-      lv_anim_set_values(&a, 0, micValue);
-      lv_anim_start(&a);
     }
+}
+```
 
-    // Clear the read count
-    samplesRead = 0;
-    delay(10);
-  }
-  lv_timer_handler();
+Its inside this `for` loop where we can get readings that will then change visual elements on the screen. This is where you would put any code that needs to react to the microphone readings.
+
+And the last important part is the callback function that we used in the `setup()` function. This will take care of reading the values into the buffer and setting the value of the `samplesRead` variable which we used in the previous step.
+
+
+```arduino
+/**
+ * Callback function to process the data from the PDM microphone.
+ * NOTE: This callback is executed as part of an ISR.
+ * Therefore using `Serial` to print messages inside this function isn't supported.
+ * */
+void onPDMdata() {
+  // Query the number of available bytes
+  int bytesAvailable = PDM.available();
+
+  // Read into the sample buffer
+  PDM.read(sampleBuffer, bytesAvailable);
+
+  // 16-bit, 2 bytes per sample
+  samplesRead = bytesAvailable / 2;
 }
 ```
 
-In the section below you can find the full sketch. If you upload it to your GIGA Display Shield, you should see the same result as the GIF below is showing.
+### Clap Detection Sketch
 
-[GIF of sketch running]()
+This sketch uses the [Arduino_Graphics library](https://www.arduino.cc/reference/en/libraries/arduinographics/) to change the color of the background when a loud noise is detected, such as a clap.
+
+```arduino
 
-### Full Sketch
+```
+
+### Volume Indication Sketch
 
-You will find the full sketch in the example below:
+This sketch requires the [lvgl library](https://github.com/lvgl/lvgl), please make sure that is installed before you upload the sketch. The sketch will show a bar on the screen that is animated when noise is made, functionally making it display the volume of the microphones readings. For more information about using lvgl with the GIGA Display Shield, take a look at our documentation [here](tutorials/lvgl-guide). You will find the full sketch below:
 
 ```arduino
 #include <PDM.h>
@@ -198,9 +192,12 @@ void onPDMdata() {
 }
 ```
 
+
+[GIF of sketch running]()
+
 ## Conclusion
 
-Now you know how to get readings from the GIGA Display Shield's on-board microphone and how to create simple visual elements with LVGL. And lastly, how these two components could be put together in a sketch to utilize the shield's screen and on-board components.
+Now you know how to get readings from the GIGA Display Shield's on-board microphone and how to create simple visual elements that react to those readings.
 
 ## Next Step
 Now that you know how to use the on-board microphone, feel free to explore the shield's other features, like the IMU with our [Orientation tutorial](/tutorials/image-orientation). Or if you rather dive deeper into LVGL, take a look at our [LVGL guide](tutorials/lvgl-guide).