Skip to content

Commit 9780d9d

Browse files
DhruvaG2000DhruvaG2000
committed
Add Documentation
- specify reqd changes CMakelist - User needs to know that they will have to change the CMakelists of their sample to find their board specific overlay - 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]> - create arduino_libs to explain using external libs This page explains how to use an external arduino library with your project Signed-off-by: Dhruva Gole <[email protected]> update README: add Link to docs folder Also add links to both golioth and my blog Signed-off-by: Dhruva Gole <[email protected]> - Update README: add links to the doc mds Helps users to locate documentation more easily Co-authored-by: Mike Szczys <[email protected]> - Be explicit on how to add the source file to the build Signed-off-by: Dhruva Gole <[email protected]>
1 parent dcfa045 commit 9780d9d

File tree

3 files changed

+159
-1
lines changed

3 files changed

+159
-1
lines changed

Diff for: ‎README.md

+8-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@
44

55
## Arduino Core API module for zephyr
66

7-
Arduino Core API module for zephyr leverages the power of Zephyr under an Arduino-C++ style abtraction layer thus helping zephyr new-comers to start using it without worrying about learning about new APIs and libraries. Visit this project's [official blog](https://dhruvag2000.github.io/Blog-GSoC22/) for documentation.
7+
Arduino Core API module for zephyr leverages the power of Zephyr under an Arduino-C++ style abtraction layer thus helping zephyr new-comers to start using it without worrying about learning about new APIs and libraries. See the project documentation folder for detailed documentation on these topics:
8+
9+
* [Using external Arduino Libraries](/documentation/arduino_libs.md)
10+
* [Adding custom boards/ variants](/documentation/variants.md)
811

912
## Adding Arduino Core API to Zephyr
1013

@@ -44,3 +47,7 @@ The `cores` folder can be found at `~/zephyrproject/modules/lib/Arduino-Zephyr-A
4447

4548
## License
4649
Please note that the current license is Apache 2. Previously it was LGPL 2.1 but after careful review it was determined that no LGPL code or derivates was used and the more permissive license was chosen.
50+
51+
**Additional Links**
52+
* [Official Project Blog](https://dhruvag2000.github.io/Blog-GSoC22/)
53+
* Golioth's Article: [Zephyr + Arduino: a Google Summer of Code story](https://blog.golioth.io/zephyr-arduino-a-google-summer-of-code-story/)

Diff for: ‎documentation/arduino_libs.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Using external Arduino Libraries
2+
3+
A sample has been provided here using [ADXL345: ArduinoCore-Demo](https://github.com/DhruvaG2000/ArduinoCore-Demo).
4+
5+
Let's assume the structure of your application for simplicity to be,
6+
7+
```tree
8+
├── blinky_arduino
9+
│   ├── CMakeLists.txt
10+
│   ├── prj.conf
11+
│   ├── README.rst
12+
│   └── src
13+
│   └── main.cpp
14+
```
15+
16+
17+
## Update contents of src folder
18+
Paste your library's source files like ``ADXL345.h`` and ``ADXL345.cpp`` in your project's src folder.
19+
20+
## Update CMakeLists
21+
As we can see, there is a Top-level CMakelists which needs to be updated with your external library's source files.
22+
For example, we add `target_sources(app PRIVATE src/ADXL345.cpp)` to CMakeLists.txt.
23+
24+
## Update main.cpp
25+
Finally, paste your required code using the library in ``main.c`` and include that library's header using
26+
```c
27+
#include "ADXL345.h"
28+
```

Diff for: ‎documentation/variants.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Adding custom boards/ variants
2+
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.
32+
33+
```tree
34+
variants/
35+
├── arduino_nano_33_ble
36+
│   ├── arduino_nano_33_ble.overlay
37+
│   └── arduino_nano_33_ble_pinmap.h
38+
├── CMakeLists.txt
39+
└── variants.h
40+
41+
```
42+
43+
- The top level consists of `CMakeLists.txt`, `variants.h` and the `<BOARD_NAME>` folder. Each of these files have a specific role to play.
44+
- The `Cmakelists` help the compiler locate the proper directory to help find the proper header files that are board specific. You need to add the name using `zephyr_include_directories(BOARD_NAME)` to this file. Do note that this `BOARD_NAME` is the same as the name of your board's directory.
45+
- `variants.h` contains the necessary `#includes` inorder to tell the source code about your board's pinmap.
46+
- 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.
47+
48+
## Guide to Writing Overlays
49+
50+
### DeviceTree Overlay files for Arduino boards
51+
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)