Docs: describe how to make overlays

Add guidance on how to map the Arduio Header in overlay files
Also rename Docs to docs to match lower case convention of other folders

Signed-off-by: Mike Szczys <[email protected]>
Signed-off-by: Dhruva Gole <[email protected]>

Author: szczys

Diff for: Documentation/overlays.md

@@ -0,0 +1,95 @@
+# How to add board variants
+
+This module uses the board name (supplied at build time by the `-b
+arduino_nano_33_ble` flag) to correctly map Arduino pin names/numbers to the
+target board. To add board support:
+
+1. Add a folder inside of the variants folder that matches the name of your
+   board
+2. Add an overlay file and a pinmap header file that match the name of the board
+3. Add your new headerfile to an `#ifdef` statement in the variants.h file
+
+An example of this structure is shown below.
+
+```tree
+├── variants
+│   ├── arduino_nano_33_ble
+│   │   ├── arduino_nano_33_ble.overlay
+│   │   └── arduino_nano_33_ble_pinmap.h
+```
+
+## DeviceTree Overlay files for Arduino boards
+
+This module requires that your Arduino header pins be mapped in the DeviceTree
+to a `zephyr,user` node using the `d0_gpios` format for each pin. Follow the
+examples in the variants directory to create an overlay file and a header file
+for your board.
+
+### Overlays using previously-defined Arduino headers
+
+When an Arduino header exists in a board's in-tree DTS file it can easily be
+used to create the necessary overlay file. Assign the relevant mapping using the
+Arduino header label (usually either `&arduino_header` or `&arduino_nano_header`
+and the `gpio_map` number. The second number is used to add GPIO flags and may
+safely be left as zero.
+
+For example, creating an overlay file for the Nordic nRF52840 Development Kit
+uses [the Arduino header definitions](https://github.com/zephyrproject-rtos/zephyr/blob/6f8ee2cdf7dd4d746de58909204ea0ce156d5bb4/boards/arm/nrf52840dk_nrf52840/nrf52840dk_nrf52840.dts#L74-L101), beginning with the first digital pin:
+
+```
+/ {
+	zephyr,user {
+		d0_gpios = <&arduino_header 6 0>;			/* Digital */
+		d1_gpios = <&arduino_header 7 0>;
+		...
+		d13_gpios = <&arduino_header 19 0>;
+		d14_gpios = <&arduino_header 0 0>;			/* Analog */
+		d15_gpios = <&arduino_header 1 0>;
+		...
+		d19_gpios = <&arduino_header 5 0>;
+		d20_gpios = <&arduino_header 20 0>;			/* SDA */
+		d21_gpios = <&arduino_header 21 0>;			/* SCL */
+		d22_gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;	/* LED0 */
+	};
+};
+```
+
+### Overlays from scratch
+
+You can see in the example above that there is no mapping for `LED0` in the
+board's Arduino header definition so it has been added using the Zephyr `gpios`
+syntax (port, pin, flags). When creating an overlay file that doesn't have an
+Arduino header defined, you should follow this syntax for adding all pins
+
+### You control the pin mapping
+
+Zephyr [chooses to map Arduino headers beginning with the Analog
+pins](https://docs.zephyrproject.org/latest/build/dts/api/bindings/gpio/arduino-header-r3.html),
+but the overlay file example above begins with the digital pins. This is to
+match user
+expectation that issuing `pinMode(0,OUTPUT);` should control digital pin 0 (and
+not pin 6). In the same way, the Analog 0 pin was mapped to D14 as this is
+likely what a shield made for the Arduino Uno R3 header would expect.
+
+Ultimately the mapping is completely up to you and should match the needs of the
+sketch you will be compiling.
+
+## Creating the pinmap header file
+
+It is recommended that you copy an existing pinmap file from one of the board
+folders inside of the variants folder. For the most part, this header file will
+not change from board to board.
+
+One example of a change that you may find useful is mapping additional pins. For
+example, the LEDs on the nRF52840 are not connected to any of the Arduino header
+pins. To define a built-in LED for this board, a 22nd pin definition was added.
+
+Your pinmap header file must be added to the variants.h file by adding three
+lines using this format:
+
+```c
+#ifdef CONFIG_BOARD_NRF52840DK_NRF52840
+#include "nrf52840dk_nrf52840.h"
+#endif // CONFIG_BOARD_NRF52840DK_NRF52840
+```
+