Skip to content

Commit 780dea0

Browse files
DhruvaG2000DhruvaG2000
committed
docs: variants: Update docs
Restructure and merge the overlays.md into variants and rm overlays Signed-off-by: Dhruva Gole <[email protected]>
1 parent 39ef189 commit 780dea0

File tree

2 files changed

+103
-109
lines changed

2 files changed

+103
-109
lines changed

Diff for: ‎documentation/overlays.md

-95
This file was deleted.

Diff for: ‎documentation/variants.md

+103-14
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,35 @@
11
# Adding custom boards/ variants
22

3-
**Pre-reqs:** <br>
4-
- It is most recommended that if you have a highly custom board that even zephyr-RTOS doesn't support yet then you should add support for it first there.
5-
- You need to satisfy all requirements mentioned in the project's README.
3+
- Boards already supported by Zephyr can be added to the variants folder as outlined in this documentation.
4+
- Custom boards can first by added by following the [official Zephyr porting guide](https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html).
5+
Once completed, continue here by adding a variant for your custom board.
6+
7+
## Suppored Boards/variants
8+
9+
- [X] Arduino Nano ble sense 33
10+
- [X] Arduino Nano ble 33
11+
- [X] Arduino Nano 33 iot
12+
13+
## Planned Support: (TODO)
14+
- [ ] Particle Xenon
15+
- [ ] Arduino mkrzero
16+
- [ ] TI-CC3220SF LaunchXL
17+
- [ ] nrf52840dk_nrf52840
18+
19+
## How to add board variants
20+
21+
This module uses the board name (supplied at build time by the `-b
22+
arduino_nano_33_ble` flag) to correctly map Arduino pin names/numbers to the
23+
target board. To add board support:
24+
25+
1. This project is structured in a way so as to isolate the variants from the core API. Thus, whenever a new board
26+
needs to be added it needs to be done in the `variants/` folder.
27+
Add a folder inside of the variants folder that matches the name of your board.
28+
2. Add an overlay file and a pinmap header file that match the name of the board.
29+
3. Add your new headerfile to an `#ifdef` statement in the variants.h file.
30+
31+
An example of this structure is shown below.
632

7-
**General Instructions:** <br>
8-
- The project is structures in a way so as to isolate the variants from the core API. Thus, whenever a new board needs to be added it needs to be done in the `variants/` folder.
9-
- The structure of the variants folder with the help of an example is as follows:
1033
```tree
1134
variants/
1235
├── arduino_nano_33_ble
@@ -22,13 +45,79 @@ variants/
2245
- `variants.h` contains the necessary `#includes` inorder to tell the source code about your board's pinmap.
2346
- The `<BOARD_NAME>` folder is where the overlay and pinmap file resides. Inorder to understand how to write DT overlays, lookup `Documentation/overlays.md`. To understand the `<boardname_pinmap.h> file, go through the existing `variants/ARDUINO_NANO33BLE/arduino_nano_ble_sense_pinmap.h` which shows how to use the overlay nodes inside our C programs using zephyr macros like `GPIO_DT_SPEC_GET`. The zephyr-project documentation on this is pretty extensive as well and worth reading.
2447

25-
## Suppored Boards/variants
48+
## Guide to Writing Overlays
2649

27-
- [X] Arduino Nano ble sense 33
28-
- [X] Arduino Nano ble 33
29-
- [X] Arduino Nano 33 iot
50+
### DeviceTree Overlay files for Arduino boards
3051

31-
## Planned Support: (TODO)
32-
- [ ] Particle Xenon
33-
- [ ] Arduino mkrzero
34-
- [ ] TI-CC3220SF LaunchXL
52+
This module requires that your Arduino header pins be mapped in the DeviceTree
53+
to a `zephyr,user` node using the `d0_gpios` format for each pin. Follow the
54+
examples in the variants directory to create an overlay file and a header file
55+
for your board.
56+
57+
### Overlays using previously-defined Arduino headers
58+
59+
When an Arduino header exists in a board's in-tree DTS file it can easily be
60+
used to create the necessary overlay file. Assign the relevant mapping using the
61+
Arduino header label (usually either `&arduino_header` or `&arduino_nano_header`
62+
and the `gpio_map` number. The second number is used to add GPIO flags and may
63+
safely be left as zero.
64+
65+
For example, creating an overlay file for the Nordic nRF52840 Development Kit
66+
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:
67+
68+
```
69+
/ {
70+
zephyr,user {
71+
d0_gpios = <&arduino_header 6 0>; /* Digital */
72+
d1_gpios = <&arduino_header 7 0>;
73+
...
74+
d13_gpios = <&arduino_header 19 0>;
75+
d14_gpios = <&arduino_header 0 0>; /* Analog */
76+
d15_gpios = <&arduino_header 1 0>;
77+
...
78+
d19_gpios = <&arduino_header 5 0>;
79+
d20_gpios = <&arduino_header 20 0>; /* SDA */
80+
d21_gpios = <&arduino_header 21 0>; /* SCL */
81+
d22_gpios = <&gpio0 13 GPIO_ACTIVE_LOW>; /* LED0 */
82+
};
83+
};
84+
```
85+
86+
### Overlays from scratch
87+
88+
You can see in the example above that there is no mapping for `LED0` in the
89+
board's Arduino header definition so it has been added using the Zephyr `gpios`
90+
syntax (port, pin, flags). When creating an overlay file that doesn't have an
91+
Arduino header defined, you should follow this syntax for adding all pins
92+
93+
### You control the pin mapping
94+
95+
Zephyr [chooses to map Arduino headers beginning with the Analog
96+
pins](https://docs.zephyrproject.org/latest/build/dts/api/bindings/gpio/arduino-header-r3.html),
97+
but the overlay file example above begins with the digital pins. This is to
98+
match user
99+
expectation that issuing `pinMode(0,OUTPUT);` should control digital pin 0 (and
100+
not pin 6). In the same way, the Analog 0 pin was mapped to D14 as this is
101+
likely what a shield made for the Arduino Uno R3 header would expect.
102+
103+
Ultimately the mapping is completely up to you and should match the needs of the
104+
sketch you will be compiling.
105+
106+
## Creating the pinmap header file
107+
108+
It is recommended that you copy an existing pinmap file from one of the board
109+
folders inside of the variants folder. For the most part, this header file will
110+
not change from board to board.
111+
112+
One example of a change that you may find useful is mapping additional pins. For
113+
example, the LEDs on the nRF52840 are not connected to any of the Arduino header
114+
pins. To define a built-in LED for this board, a 22nd pin definition was added.
115+
116+
Your pinmap header file must be added to the variants.h file by adding three
117+
lines using this format:
118+
119+
```c
120+
#ifdef CONFIG_BOARD_NRF52840DK_NRF52840
121+
#include "nrf52840dk_nrf52840.h"
122+
#endif // CONFIG_BOARD_NRF52840DK_NRF52840
123+
```

0 commit comments

Comments
 (0)