Docs: describe how to make overlays

Add guidance on how to map the Arduio Header in overlay files

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

Author: szczys

Diff for: Documentation/overlays.md

@@ -1,6 +1,95 @@
-# DT Overlays
+# How to add board variants
 
-Once you create the overlay files inside ``variants/<BOARD_NAME>`` you need to make zephyr understand where it is or else it simply will not find the overlay file and throw errors.
-Inorder to point the build system to your overlay file, you need to modify the ``samples/CMakeLists`` file and replace ``set(DTC_OVERLAY_FILE $ENV{HOME}/zephyrproject/modules/lib/Arduino-Zephyr-API/variants/ARDUINO_NANO33BLE/arduino_nano_33_ble.overlay)`` with your path.
+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
+```
 
-TODO