Adding documentation for threading basics.

Author: aentinger

docs/01-threading-basics.md

@@ -0,0 +1,101 @@
+<img src="https://content.arduino.cc/website/Arduino_logo_teal.svg" height="100" align="right"/>
+
+Threading Basics
+================
+## Introduction
+In the historic single-threaded execution of Arduino programs the complete program logic is contained within the `*.ino` file. It contains both a `setup()` function, which is executed only once at program start, and a `loop()` function, which is executed indefinitely. In order to support multi-threaded (or parallel) sketch execution a new file type called the `*.inot` file is introduced. While a Arduino program can contain one `*.ino` file, they can contain multiple `*.inot` files. Each `*.inot` file contains it's own `setup()` and `loop()` and represent separate thread.
+
+The advantage of this approach is that a complicated and a long `loop()` function (consisting of nested [finite state machines](https://en.wikipedia.org/wiki/Finite-state_machine)) found in typical Arduino sketches can be broken up in several, parallel executed `loop()` functions with a much smaller scope. This increases program readability and maintainability, directly reducing to bugs (software errors).
+
+#### Example (Single-Threaded):
+This sketch demonstrates how one would implement a program which requires the execution of three different actions on three different periodic intervals.
+**Blink_Three_LEDs.ino**:
+```C++
+void setup()
+{
+  pinMode(LED_RED,   OUTPUT);
+  pinMode(LED_GREEN, OUTPUT);
+  pinMode(LED_BLUE,  OUTPUT);
+}
+
+int const DELAY_RED_msec   = 900;
+int const DELAY_GREEN_msec = 500;
+int const DELAY_BLUE_msec  = 750;
+
+void loop()
+{
+  static unsigned long prev_red   = millis();
+  static unsigned long prev_green = millis();
+  static unsigned long prev_blue  = millis();
+
+  unsigned long const now = millis();
+
+  if ((now - prev_red) > DELAY_RED_msec) {
+    prev_red = now;
+    digitalWrite(LED_RED, !digitalRead(LED_RED));
+  }
+
+  if ((now - prev_green) > DELAY_GREEN_msec) {
+    prev_green = now;
+    digitalWrite(LED_GREEN, !digitalRead(LED_GREEN));
+  }
+
+  if ((now - prev_blue) > DELAY_BLUE_msec) {
+    prev_blue = now;
+    digitalWrite(LED_BLUE, !digitalRead(LED_BLUE));
+  }
+}
+```
+#### Example (Multi-Threaded):
+The same functionality can be provided via multi-threaded execution in a much simpler way.
+**Blink_Three_LEDs.ino**
+```C++
+void setup() {
+  LedRed.start();
+  LedGreen.start();
+  LedBlue.start();
+}
+
+void loop() {
+
+}
+```
+**LedRed.inot**
+```C++
+void setup() {
+  pinMode(LED_RED, OUTPUT);
+}
+
+int const DELAY_RED_msec = 900;
+
+void loop() {
+  digitalWrite(LED_RED, !digitalRead(LED_RED));
+  delay(DELAY_RED_msec);
+}
+```
+**LedGreen.inot**
+```C++
+void setup() {
+  pinMode(LED_GREEN, OUTPUT);
+}
+
+int const DELAY_GREEN_msec = 500;
+
+void loop() {
+  digitalWrite(LED_GREEN, !digitalRead(LED_GREEN));
+  delay(DELAY_GREEN_msec);
+}
+```
+**LedBlue.inot**
+```C++
+void setup() {
+  pinMode(LED_BLUE, OUTPUT);
+}
+
+int const DELAY_BLUE_msec = 750;
+
+void loop() {
+  digitalWrite(LED_BLUE, !digitalRead(LED_BLUE));
+  delay(DELAY_BLUE_msec);
+}
+```

docs/README.md

@@ -0,0 +1,15 @@
+<img src="https://content.arduino.cc/website/Arduino_logo_teal.svg" height="100" align="right"/>
+
+`Arduino_Threads/docs`
+======================
+The Arduino threading APIs brings multi-threading to the world of Arduino.
+
+The following Arduino architectures and boards are supported:
+* `mbed_portenta`: [Portenta H7](https://store.arduino.cc/products/portenta-h7)
+* `mbed_nano`: [Nano 33 BLE](https://store.arduino.cc/arduino-nano-33-ble), [Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect)
+* `mbed_edge`: [Edge Control](https://store.arduino.cc/products/arduino-edge-control)
+
+Threading on Arduino can be achieved by leveraging the [Arduino_Threads](https://github.com/bcmi-labs/Arduino_Threads) library in combination with [arduino-cli](https://github.com/facchinm/arduino-cli/commits/arduino_threads_rebased).
+
+### Table of Contents
+* [Threading Basics](01-threading-basics.md)