Merge pull request #534 from arduino/karlsoderby/gds-fixes-monday

Karlsoderby/gds fixes monday

Author: karlsoderby

content/hardware/10.mega/shields/giga-display-shield/tutorials/getting-started/assets/mounted.png renamed to content/hardware/10.mega/shields/giga-display-shield/tutorials/01.getting-started/assets/mounted.png

@@ -0,0 +1,159 @@
+---
+title: 'Getting Started with the GIGA Display Shield'
+description: 'Learn how to set up and use the GIGA Display Shield and get an overview of its features.'
+author: 'Karl Söderby'
+hardware:
+  - hardware/08.mega/boards/giga-r1-wifi
+  - hardware/08.mega/shields/giga-display-shield
+tags: [Display, Touch, LVGL, GIGA, IMU, GFX]
+---
+
+The [GIGA Display Shield](/hardware/giga-display-shield) is an accessory shield designed for the [GIGA R1 WiFi](/hardware/giga-r1-wifi) board. With it, you can render fast & sophisticated user interfaces on a **800x480** display with **touch support**.
+
+In this guide you will learn how to set your board up with the GIGA R1 WiFi board & become familiar with the available libraries to control it.
+
+## Hardware & Software Needed
+
+- [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi).
+- [GIGA Display Shield](https://store.arduino.cc/products/giga-display-shield)
+- [Arduino IDE](https://www.arduino.cc/en/software)
+
+## Overview
+
+To use the GIGA Display Shield, there are currently three supported alternatives to draw on the display.
+
+### Option 1: GFX Library
+
+The [Arduino_GigaDisplay_GFX](https://github.com/arduino/Arduino_GigaDisplay_GFX) library is a layer library for the [Adafruit_GFX](https://github.com/adafruit/Adafruit-GFX-Library) graphic core library. This library makes it easy to draw geometrical shapes, printing values, drawing pixels and more. 
+
+To get started with the GFX library, visit the [GIGA Display Shield GFX Guide](/tutorials/giga-display-shield/gfx-guide).
+
+### Option 2: LVGL
+
+The LVGL framework supports building more advanced UIs with dropdown menus, interactive buttons, scroll functionality using a grid system.
+
+To get started, visit the [GIGA Display LVGL Guide](/tutorials/giga-display-shield/lvgl-guide)
+
+### Option 3: ArduinoGraphics
+
+[ArduinoGraphics](https://www.arduino.cc/reference/en/libraries/arduinographics/) is a simple library for more primitive drawings with a similar API to the GFX library.
+
+To get started, visit the [GIGA Display Shield Draw Images Guide](/tutorials/giga-display-shield/basic-draw-and-image).
+
+## Core & Libraries
+
+The GIGA Display Shield requires you to install the core for GIGA boards, along with some additional software libraries.
+
+The libraries can be installed via the Arduino IDE's library manager, where you will also discover examples.
+
+### GIGA Core
+
+To use the shield you will need a [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi) board. You also need to install the **GIGA core**, which can be done directly in the Arduino IDE, under "Board Manager". The source code for this core can be found in [this GitHub repository](https://github.com/arduino/ArduinoCore-mbed).
+
+***For more details, see [Getting Started with GIGA R1 WiFi](/tutorials/giga-r1-wifi/giga-getting-started).***
+
+### Arduino_H7_Video
+
+The [Arduino_H7_Video](https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video) manages the video output and integrates third party frameworks such as [LVGL](https://lvgl.io/). This library is used to configure and initialize the display and to perform basic draw functions.
+
+***This library is included with the GIGA core, and does not need to be installed. The documentation for this library is available [here](https://github.com/arduino/ArduinoCore-mbed/tree/main/libraries/Arduino_H7_Video/docs).***
+
+### ArduinoGraphics
+
+The [ArduinoGraphics](https://www.arduino.cc/reference/en/libraries/arduinographics/) is required for drawing operations on the screen. 
+
+***For source code and issues with the ArduinoGraphics library, please see the [GitHub repository](https://github.com/arduino-libraries/ArduinoGraphics).***
+
+### Arduino_GigaDisplayTouch
+
+The [Arduino_GigaDisplayTouch](https://www.arduino.cc/reference/en/libraries/arduino_gigadisplaytouch/) is required for reading touch points on the screen, and is needed when using the LVGL's framework.
+
+***For source code and issues with the Arduino_GigaDisplayTouch library, please see the [GitHub repository](https://github.com/arduino-libraries/Arduino_GigaDisplayTouch).***
+
+### Arduino_GigaDisplay_GFX
+
+The [Arduino_GigaDisplay_GFX](https://github.com/arduino-libraries/Arduino_GigaDisplay_GFX) library is a layer library for the [Adafruit_GFX](https://github.com/adafruit/Adafruit-GFX-Library) graphics core library.
+
+This library is great for drawing geometrical shapes, printing text & values, drawing pixels and so on. It is recommended for beginners.
+
+***Learn more about this library in the [GIGA Display Shield GFX Guide](/tutorials/giga-display-shield/gfx-guide).***
+
+### Arduino_GigaDisplay
+
+The [Arduino_GigaDisplay](https://github.com/arduino-libraries/Arduino_GigaDisplay) provides a large set of examples that can be used with the shield, many of which are included in the guides found in the documentation. 
+
+This library is also required to use the built-in RGB, which you can read more about in the [RGB](#rgb) section.
+
+***This library lists out all recommended libraries as dependencies. Installing it through the IDE will also prompt you to install the libraries listed above.***
+
+### Arduino_BMI270_BMM150 (IMU)
+
+To access the onboard IMU, use the [Arduino_BMI270_BMM150](https://github.com/arduino-libraries/Arduino_BMI270_BMM150) library. 
+
+You can read more about its methods in the [library documentation](https://www.arduino.cc/reference/en/libraries/arduino_bmi270_bmm150/).
+
+More information available in the [IMU section](#imu) in this document.
+
+## Hardware Setup
+
+To use the GIGA Display Shield, mount it on the **bottom** side of the GIGA R1 WiFi board. The GIGA R1 WiFi board will be flipped upside down when the display is used.
+
+![Bottom View](assets/mounted.png)
+
+This makes it possible to freely use the GIGA R1 WiFi's pins while the display shield is connected.
+
+## Camera Connector
+
+Located on the top side of the shield is a 20 pin camera connector, which is Arducam® compatible and supports a wide range of cameras. The connector is connected to the [GIGA R1 WiFi's camera connector](/tutorials/giga-r1-wifi/giga-camera#camera-connector), and is compatible with a wide range of cameras ([see Arducam cameras](https://www.arducam.com/camera-for-arduino-giga/)).
+
+The connector is located just above the display, which makes it possible to see camera's feed directly on the display! Read more about this in the [GIGA Display Camera Connector Guide](/tutorials/giga-display-shield/camera-tutorial), complete with an example.
+
+## IMU
+
+This shield has a built-in IMU module, the **BMI270**. This sensor can be used for a number of purposes, for example to automatically orientate an object on the screen, see the following tutorial: 
+
+- [Giga Display Shield Automatic Orientation](/tutorials/giga-display-shield/image-orientation)
+
+To access **BMI270**, use the [BMI270-250](https://www.arduino.cc/reference/en/libraries/arduino_bmi270_bmm150/) library. Please note that the sensor is not connected to the main I2C bus, so you will need to initialize the sensor on another bus. To do so, simply add the line below to the top of your sketch:
+
+```arduino
+BoschSensorClass imu(Wire1);
+``` 
+
+Note that the examples use the default `IMU` (uppercase) class, which you will need to replace. Example:
+
+```
+IMU.begin() //for other boards
+imu.begin() //for GIGA Display Shield
+```
+
+## Microphone
+
+This shield has an embedded omnidirectional microphone, **MP34DT06JTR**, which can be used together with the [PDM](https://docs.arduino.cc/learn/built-in-libraries/pdm) library. This library is shipped with the GIGA core, so there's no need to manually install it.
+
+Below is a minimal sketch that will print out the samples in the serial plotter (See [Using the Serial Plotter Tool](/software/ide-v2/tutorials/ide-v2-serial-plotter) for more information). 
+
+<CodeBlock url="https://github.com/arduino/ArduinoCore-mbed/blob/main/libraries/PDM/examples/PDMSerialPlotter/PDMSerialPlotter.ino" className="arduino"/>
+
+To get started with the microphone, visit the [GIGA Display Shield Microphone Guide](/tutorials/giga-display-shield/microphone-tutorial).
+
+## RGB
+
+This shield has a built in RGB pixel that is controlled via I2C. To use this, install the [Arduino_GigaDisplay](https://github.com/arduino-libraries/Arduino_GigaDisplay) library. The following sketch is a minimal example that will blink the blue pixel every second.
+
+```arduino
+#include <Arduino_GigaDisplay.h>
+
+GigaDisplayRGB rgb; //create rgb object
+
+void setup() {
+  rgb.begin(); //init the library
+}
+
+void loop() {
+  rgb.on(0, 0, 255); //turn on blue pixel
+  delay(1000);
+  rgb.off(); //turn off all pixels
+  delay(1000);
+}
+```

content/hardware/10.mega/shields/giga-display-shield/tutorials/01.getting-started/getting-started.md

@@ -1,11 +1,11 @@
 ---
-title: Using Draw and Image Functions with the GIGA Display Shield
+title: GIGA Display Shield Draw Images Guide
 description: 'Learn how to use basic draw functions to create and display images on the GIGA Display Shield.'
 author: Benjamin Dannegård
 hardware:
   - hardware/10.mega/boards/giga-r1-wifi
   - hardware/10.mega/shields/giga-display-shield
-tags: [Display, Draw]
+tags: [Display, Draw, Images]
 ---
 
 The most basic use of the GIGA Display Shield is to draw an image on the screen using code. This is made easy by using the library `ArduinoGraphics`. In this tutorial we will go through how to draw the Arduino logo on the GIGA Display Shield with the commands provided by this library.

content/hardware/10.mega/shields/giga-display-shield/tutorials/getting-started/hero-banner.png renamed to content/hardware/10.mega/shields/giga-display-shield/tutorials/01.getting-started/hero-banner.png

@@ -0,0 +1,201 @@
+---
+title: 'GIGA Display Shield Touch Interface'
+description: 'Learn how to use the touch interface on the GIGA Display Shield.'
+author: Karl Söderby
+tags: [Display, Touch Screen]
+---
+
+The [GIGA Display Shield](/hardware/giga-display-shield) has an advanced touch interface, supported via the [Arduino_GigaDisplayTouch](https://github.com/arduino-libraries/Arduino_GigaDisplayTouch) library.
+
+This library is used to return the number of contact points, and the `x,y` coordinates for each of contacts, and in this guide you will learn about different methods to obtain the data.
+
+## Hardware & Software Needed
+
+- [GIGA R1 WiFi](/hardware/giga-r1-wifi).
+- [GIGA Display Shield](/hardware/giga-display-shield)
+- [Arduino IDE](https://www.arduino.cc/en/software)
+
+## Overview
+
+The **Arduino_GigaDisplayTouch** library can be used in combination with any of the available graphics libraries ([see available options](/tutorials/giga-display-shield/getting-started#overview)), but is independent from them and works standalalone.
+
+The library has two methods of reading sensor data:
+- **Polling** - continuously read the sensor data through the `getTouchPoint()` method.
+- **IRQ** - only read data when the display is touched through an interrupt and a callback function, using the `onDetect()` method.
+
+The number of contacts (fingers touching) can be retrieved and stored as an integer:
+
+```arduino
+contacts = touchDetector.getTouchPoints(points);
+```
+
+To read the `x` and `y` coordinates, we need to use a specific `struct` called `GDTpoint_t` which contains the values. The example belows simply iterates through the number of `contacts` and stores the coordinates of each contact.
+
+```arduino
+GDTpoint_t points[5];
+uint8_t contacts;
+
+for (uint8_t i = 0; i < contacts; i++) {
+  x_coordinate = points[i].x;
+  y_coordinate = points[i].y;
+}
+```
+
+### Touch Interface
+
+An option to consider 
+
+### Gesture Detection
+
+As you are able to retrieve multiple touch points at very fast rates, it is possible to create **gesture detections**. You could for example:
+- change layout when swiping three fingers right,
+- zoom in and out using two fingers,
+- adjust the volume by swiping a finger from the bottom right corner and up,
+- and many more scenarios.
+
+This library can together with the supported graphics libraries create really interactions that we are using in modern day smartphones, tablets etc., with an easy interface and very fast response times.
+
+## Polling Example
+
+The polling example demonstrates how to continuously read the touch sensor using the `getTouchPoints()` method. Whenever the display screen is touched, the number of contacts + the coordinates of each contact is printed to the Serial Monitor.
+
+<CodeBlock url="https://github.com/arduino-libraries/Arduino_GigaDisplayTouch/blob/main/examples/Touch_Polling/Touch_Polling.ino" className="arduino"/>
+
+## IRQ Example
+
+The IRQ example demonstrates how to set up an interrupt that triggers a function anytime the screen is touched. The interrupt is set up inside of the `setup()` function, using the `onDetect(function)` method. 
+
+<CodeBlock url="https://github.com/arduino-libraries/Arduino_GigaDisplayTouch/blob/main/examples/Touch_IRQ/Touch_IRQ.ino" className="arduino"/>
+
+## Delay Example
+
+An important factor to consider is that the `loop()` on the GIGA R1 is executed at a very fast rate, meaning that you will register several touches each time you touch the screen.
+
+This means that whenever you tap the screen, even quickly, you register somewhere between **5-20 touches**. So if you want a specific function to only execute once on a specific touch point, you will need to implement a delay in your code. 
+
+Using the conventional, but blocking `delay(microseconds)` method is possible but not ideal. The best method to register only a single touch is through using the `millis()` method.
+
+The example below is based on the **Polling Example**, and limits the if statement to only execute once every `250` milliseconds. This can be edited in the `threshold` variable.
+
+```arduino
+#include "Arduino_GigaDisplayTouch.h"
+
+Arduino_GigaDisplayTouch touchDetector;
+int lastTouch;
+int threshold = 250; //time in milliseconds
+
+void setup() {
+  Serial.begin(115200);
+  while(!Serial) {}
+
+  if (touchDetector.begin()) {
+    Serial.print("Touch controller init - OK");
+  } else {
+    Serial.print("Touch controller init - FAILED");
+    while(1) ;
+  }
+}
+
+void loop() {
+  uint8_t contacts;
+  GDTpoint_t points[5];
+  
+  contacts = touchDetector.getTouchPoints(points);
+
+  // check if more time than the threshold defined has passed
+  if (contacts > 0 && (millis() - lastTouch > threshold) ) {
+    Serial.print("Contacts: ");
+    Serial.println(contacts);
+
+    for (uint8_t i = 0; i < contacts; i++) {
+      Serial.print(points[i].x);
+      Serial.print(" ");
+      Serial.println(points[i].y);
+    }
+    lastTouch = millis(); // register last touch
+  }
+
+  delay(1);
+}
+```
+
+## GFX Touch Example
+
+The below example requires uses the [Arduino_GigaDisplay_GFX](https://github.com/arduino/Arduino_GigaDisplay_GFX) library, and demonstrates how to change a boolean whenever you touch the screen. It implements the `millis()` function to limit the number of executions. 
+
+Anytime the screen is touched, the background and text color inverts (black and white). 
+
+```arduino
+#include "Arduino_GigaDisplay_GFX.h"
+#include "Arduino_GigaDisplayTouch.h"
+
+Arduino_GigaDisplayTouch touchDetector;
+GigaDisplay_GFX display;
+
+#define WHITE 0xffff
+#define BLACK 0x0000
+
+#define screen_size_x 480
+#define screen_size_y 800
+
+int touch_x;
+int touch_y;
+
+int lastTouch;
+int threshold = 250;
+
+bool switch_1;
+
+void setup() {
+  // put your setup code here, to run once:
+  Serial.begin(9600);
+  display.begin();
+
+  if (touchDetector.begin()) {
+    Serial.print("Touch controller init - OK");
+  } else {
+    Serial.print("Touch controller init - FAILED");
+    while (1)
+      ;
+  }
+  changeSwitch();
+}
+
+void loop() {
+  uint8_t contacts;
+  GDTpoint_t points[5];
+  contacts = touchDetector.getTouchPoints(points);
+  
+  if (contacts > 0 && (millis() - lastTouch > threshold)) {
+    Serial.print("Contacts: ");
+    Serial.println(contacts);
+
+    //record the x,y coordinates 
+    for (uint8_t i = 0; i < contacts; i++) {
+      touch_x = points[i].x;
+      touch_y = points[i].y;
+    }
+
+    //as the display is 480x800, anywhere you touch the screen it will trigger
+    if (touch_x < screen_size_x && touch_y < screen_size_y) {
+      switch_1 = !switch_1;
+      Serial.println("switched");
+      changeSwitch();
+    }
+    lastTouch = millis();
+  }
+}
+
+void changeSwitch() {
+  if (switch_1) {
+    display.fillScreen(BLACK);
+    display.setTextColor(WHITE);
+  } else {
+    display.fillScreen(WHITE);
+    display.setTextColor(BLACK);
+  }
+  display.setCursor(50, screen_size_y/2);
+  display.setTextSize(5);
+  display.print("Switched");
+}
+```

content/hardware/10.mega/shields/giga-display-shield/tutorials/gfx-guide/assets/shapes-on-display.svg renamed to content/hardware/10.mega/shields/giga-display-shield/tutorials/02.gfx-guide/assets/shapes-on-display.svg

@@ -1,5 +1,5 @@
 ---
-title: Screen Orientation With IMU Readings
+title: GIGA Display Shield Automatic Screen Orientation with IMU
 description: "Learn how to use the GIGA Display Shield's IMU to determine the shield's orientation."
 author: Benjamin Dannegård
 tags: [Display, IMU, orientation, LVGL]

content/hardware/10.mega/shields/giga-display-shield/tutorials/gfx-guide/assets/text-on-display.svg renamed to content/hardware/10.mega/shields/giga-display-shield/tutorials/02.gfx-guide/assets/text-on-display.svg

@@ -1,5 +1,5 @@
 ---
-title: GIGA Display Shield Microphone & LVGL Tutorial
+title: GIGA Display Shield Microphone Guide
 description: "Learn how to use the GIGA Display Shield's microphone with LVGL."
 author: Benjamin Dannegård
 tags: [Display, microphone, LVGL]